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ABOUT TfflS BOOK 



This book describes the use of Access Method Services commands, a group of 
utility functions vital to Virtual Storage Access Method (VSAM). This 
publication provides VSAM information required to use Access Method 
Services to establish and maintain data sets. For information on VSAM data 
set and catalog format and structure, see Planning for Enhanced VSAM 
Under OS/VS, GC26-3842. For information on the use of VSAM macro 
instructions, VSAM optimization options, and various VSAM algorithms 
affecting performance, see OS/VS Virtual Storage Access Method (VSAM) 
Programmer's Guide, GC26-3838. 

Readers of this book are presumed to have a background in programming. 

This book has the following major divisions: 

• "Guide to Access Method Services," which Usts functions and the Access 
Method Services commands used to perform them. 

• "Introduction," which provides an overview of Access Method Services, 
including general language considerations and the use of Time Sharing 
Option (TSO) and the 3850 Mass Storage System with VSAM and Access 
Method Services. Everyone who intends to use Access Method Services 
should first read this chapter. 

• "Data Security and Protection," which describes the recovery features of 
VSAM that are specified as options in Access Method Services commands. 

• "Creating and Cataloging Objects," which describes the use of the 
DEFINE command to define catalogs, data spaces, VSAM data sets, 
alternate indexes, paths, and page spaces, and to catalog generation data 
groups, aliases and nonVSAM data sets. 

• "Building an Alternate Index," which describes the use of the BLDINDEX 
command to build an alternate index. An alternate index allows you to 
access a data set with a new set of key values. 

• "Modifying Catalog Information," which describes the use of the ALTER 
command to modify attributes in catalog entries. 

• "Displaying Catalog Information," which describes the use of the 
LISTCAT command to list catalog entries. 

• "Deleting Catalog Entries," which describes the use of the DELETE 
command to delete catalog entries. 

• "Moving Entries," which describes the use of the IMPORT and EXPORT 
commands to create a backup copy of a data set or to move a data set or 
user catalog between systems. 

• "Converting an OS Catalog's Entries to VSAM Catalog Entries," which 
describes the use of the CNVTCAT command to convert OS catalog 
entries to VSAM catalog entries and merge them into a VSAM catalog, 

• "Restoring a Cluster's End-of-File Values," which describes the use of the 
VERIFY command to ensure that the true end-of-file is reflected in the 
catalog. 

• "Restoring Catalog Entries After System Failure," which describes the use 
of the LISTCRA, EXPORTRA, IMPORTRA, and RESETCAT 
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commands to retrieve the contents of VSAM data sets after a VSAM 
catalog is damaged. 

• "Copying and Printing," which describes the use of the REPRO command 
to copy and to reorganize data, and to convert data from 
indexed-sequential or sequential organization to VSAM organization and 
from VSAM organization to sequential organization, and to copy catalogs; 
and the use of the PRINT command to print VSAM and nonVSAM data 
sets. 

• "Listing Tape Volumes Mounted at Checkpoint," which describes the use 
of the CHKLIST command to list tape data sets that were open during a 
checkpoint. 

• "Command Format," which lists the Access Method Services commands 
and their format, describes the required and optional parameters, and 
specifies their abbreviations. There are examples with each command and a 
description of how the commands and their parameters were used. 

• "Controlling Command Execution," which describes the use of the IF, 
SET, and PARM commands to control command execution and to specify 
diagnostic aids and printed-output options. 

• "Appendix A: Examples of Jobs Using Access Method Services 
Commands," which describes how two or more Access Method Services 
commands can be used together to accomplish a task. 

• "Appendix B: Interpreting LISTCAT Output Listings," which provides 
information on the structure of LISTCAT output and shows sample 
output. 

• "Appendix C: JCL DD Parameters to Take Care With," which describes 
JCL parameters that have either no effect in a VSAM environment or that 
have a negative effect. 

• "Appendix D: Interpreting LISTCRA Output Listings," which describes 
the format and uses of LISTCRA output. 

. "Appendix E: Sample Output from CHKLIST," which shows a CHKLIST 
listing and explains its contents. 

• "Appendix F: Command Reference Summary" which shows the format of 
each Access Method Sen/ices commaRd, parameter abbreviations, and 
defaults. The commands are grouped together to allow you to remove these 
pages and use them as a quick reference guide. 

• "Appendix G: Invoking Access Method Services from a Problem 
Program," which describes how Access Method Services may be 
dynamically invoked from a user's problem program. 

• "Appendix H: Changing the Attributes of the VSAM Master Catalog," 
which describes how to apply new attributes to the VSAM master catalog; 
for example, changing it from nonrecoverable to recoverable. 

• "Glossary," which defines terms relevant to Access Method Services and 
VSAM. 

• "Index," which is a subject index to the book. 
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Required Publications 



Related Publications 



The reader should be familiar with information presented in the following 
publications: 

• OS/VS Virtual Storage Access Method (VSAM): Programmer's Guide, 
GC26-3838, which provides information on VSAM optimization options 
and various VSAM algorithms affecting performance, macro instructions 
used to process VSAM data sets, and how to use an ISAM processing 
program to process a VSAM data set or an indexed-sequential data set that 
has been converted to VSAM format. 

• Planning for Enhanced VSAM Under OS/VS, GC26-3842, which 
includes information on the structure and contents of VSAM catalogs and 
data sets and also information on protecting VSAM catalogs and data sets. 

• OS/VS 2 MVS Utilities, GC26-3902, which describes the utility programs 
available for use with nonVSAM data sets on OS/VS2 systems. 

• OS/VS2 MVS Data Management Services Guide, GC26-3875, which 
presents basic concepts such as access method, direct-access storage, and 
the distinction between data-set organization and data-set processing. 

. OS/VS2 JCL, GC28-0692, which describes the JCL parameters referred 
to in this publication. 

• OS/VS Message Library: VS2 System Messages, GC38-1002, which 
provides a complete Usting of the messages issued by Access Method 
Services in a VS2 system. 

• OS/VS 2 System Programming Library: System Generation Reference, 
GC26-3792, which provides information necessary to install an MVS 
system control program. 



The following publications contain information that is related to this 
publication: 

• OS/VS Virtual Storage Access Method (VSAM): Options for Advanced 
Applications, GC26-3819, which provides information about advanced 
applications of VSAM which the reader doesn't need to know about to 
make normal use of VSAM. The topics covered include: gaining access to 
control intervals; I/O buffering; constructing parameter lists for the 
macros that generate, modify, and examine control blocks at execution; 
and processing an index as data. 

• OS/VS2 Checkpoint/ Restart, GC26-3877, which explains how to take 
checkpoints and to restart processing. 

• Introduction to the IBM 3850 Mass Storage System (MSS), 

G A3 2-0028, which introduces the storage devices and programming of the 
Mass Storage System. 

• OS/VS Mass Storage System (MSS) Services: Reference Information, 
GC35-0017, which describes the Mass Storage System Access Method 
Services commands for the Mass Storage System. 

• OS/VS 2 System Programming Library: Data Management, GC26-3830, 
which describes how to use the PROTECT macro. 
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Notation Conventions 



OS/VS2 System Programming Library: Supervisor, GC28-0628, which 
describes the authorized program facility. 

0S/VS2 TSO Command Language Reference, GC28-0646, which 
describes TSO commands. 

0S/VS2 TSO Terminal User's Guide, GC28-0645, which describes 
commands available to the TSO user. 

0S/VS2 System Programming Library: TSO, GC28-0629, which 
describes the TSO facilities that can be influenced by the system 
programmer. 

0S/VS2 MVS TSO Command Package: User's Guide and Reference, 
SC28-0748, which describes the TSO facilities that can be influenced by 
the system programmer. 

0S/VS2 Using OS Catalog Management with the Master Catalog: 
CVOL Processor, GC35-0010, which describes the use of control 
volumes. 

0S/VS2 Virtual Storage Access Method (VSAM) Logic, SY26-3825, 
which describes the functional operation of VSAM (Record Management, 
Open, Close, End-of- Volume, and Control Block Manipulation 
commands). 

0S/VS2 Catalog Management Logic, SY26-3826, which describes the 
functional operation of VSAM Catalog Management. 

0S/VS2 Access Method Services Logic, SY35-0O10, which describes the 
functional operation of Access Method Services Programs. 

0S/VS2 MVS Resource Access Control Facility (RACF) General 
Information Manual, GC28-0722, which contains initial planning 
information for RACF. 

0S/VS2 Resource Access Control Facility (RACF) Command Language 
Reference, SC28-0733, which describes the syntax and function of RACF 
commands. 



A uniform system of notation describes the format of Access Method Services 
commands. This notation is not part of the language; it simply provides a 
basis for describing the structure of the commands. 

The command-format illustrations in this book use the following conventions: 

• Brackets [] indicate an optional parameter. 

• Braces { } indicate a choice of entry; unless a default is indicated, you must 
choose one of the entries. 

• Items separated by a vertical bar represent alternative items. No more than 
one of the items may be selected. 

• An ellipsis ... indicates that multiple entries of the type immediately 
preceding the ellipsis are allowed. 

• Other punctuation (parentheses, commas, spaces, etc.) must be entered as 
shown. A space is indicated by b . 

• Boldface type indicates the exact characters to be entered. Such items must 
be entered exactly as illustrated (in upper case, except in TSO). 
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• Italic type specifies fields to be supplied by the user. 

• Underscored type indicates a default option. If the parameter is omitted, 
the underscored value is assumed. 
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SUMMARY OF AMENDMENTS 



July 1978 



Command parameters have been arranged in alphabetic order. 

Appendix F has been completely revised. It is now a reference summary 
showing the syntax of each command, parameter abbreviations, and defaults. 

Numerous editorial and service changes have been made throughout the book. 



OS/VS2 MVS Supervisor Perforaianee #2 (VS2.03.807) 
Auxiliary Storage Manager (ASM) Redesign 



SWAP space data sets can now be defined and preformatted. Also, a new 
integrity attribute has been added to both SWAP and PAGE spaces. 



Resource Access Control Facility (RACF) 



Changes are included to support protection of VSAM data sets through 
RACF. 



OS/VS2 MVS Data Management (VS2.03.808) 



Extended CVOL Support 



Resetting a Catalog 



In OS/VS2 MVS Release 2, the VSAM catalog replaced the system master 
catalog and support of OS CVOLs was limited to a subset of what had been 
provided in OS/VS2 SVS Release 1. Extended CVOL support provides a 
CVOL function that is equivalent to SVS while retaining the VSAM master 
catalog as the only system master catalog. This support required that changes 
be made to the section "VSAM's Use of Catalogs" and the chapter 
"Converting an OS Catalog's Entries to VSAM Catalog Entries." 



A new Access Method Services command, RESETCAT, has been added to 
support recoverable catalogs. The new command will allow you to reset your 
VSAM catalog to the level of its owned volumes. That is, if the catalog or any 
of its volumes become damaged, RESETCAT can be used to synchronize a 
catalog to a restored (not current) level version of a volume. Or, if the catalog 
has to be restored or reloaded, its entries can be changed to reflect the current 
level of its volumes with RESETCAT. The new sections "Resetting a 
Catalog" and "RESETCAT" have been added to describe and define 
parameters for this command. 
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Release 3.7 

LISTCAT Format 
Miscellaneous Topics 



The fomiat of LISTCAT output has been modified to improve readabiUty. 



Two new appendixes have been added. They are: Appendix G: Invoking 
Access Method Services from a Problem Program, and Appendix H: 
Changing the Attributes of the VSAM Master Catalog. 

All Access Method Services command formats, parameter descriptions, and 
examples have been moved to a new chapter: Command Format. In the new 
chapter, commands are arranged in alphabetical order. 

Information relating to such topics as VSAM Data Structure, How Data is 
Physically Stored, Types of VSAM Data Sets, VSAM Catalog Structure, 
Performance Optimization, and Data Integrity has been removed from this 
book. The information removed can be found in other VSAM pubhcations. 



Independent Component Release 



Alternate Index 



Reusable Data Set 



Spanned Records 



Relative-Record Data Set 



VSAM Volume Cleanup 



Following is a summary of major changes to Access Method Services for the 
release of enhanced VSAM as an independent component under OS/VS2. 



The alternate index allows you to access data records using a key field other 
than the key field established when the data set was defined (for 
key-sequenced VSAM data sets), and to access the data records of an 
entry-sequenced data set with a key field. 



The reusable data set is an attribute that can be appUed to VSAM entry 
sequenced, key sequenced, relative-record and alternate index data sets. This 
attribute allows the data set to be used for temporary storage of data. 
Whenever a reusable VSAM data set is opened, its high-used RBA can be 
reset to zero. 



Data records in VSAM data sets can be larger than one control interval, and 
are contained in two or more control intervals. 



The relative-record data set is a VSAM data set whose records are 
fixed-length and are sequenced according to record number. 



The VSAM volume cleanup process allows you to erase VSAM data from a 
volume's VTOC and reset the VTOC's format-4 DSCB to show system 
ownership of the volume. The process is to be used when a system or device 
failure occurs that damages the volume's information in its VSAM catalog 
(that is, the VSAM catalog that owns the volume). 
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VSAM Catalog Cleanup 



The ySAM catalog cleanup process allows you to delete a VSAM catalog 
without first deleting each of its cataloged entries. You can use this function 
to remove an unwanted catalog from your system. (Certain safeguards 
prevent indiscriminate use of the function.) 



Record Replacement (During REPRO) 



Catalog Recovery 



Catalf^ Recovery Area 



Exception Exit Routine 



Miscellaneous Topics 



\ 
^ 



You can merge two data sets so that, when duplicate records are encountered, 
the older record (that is, the one in the target data set) is replaced with the 
newer record (the one in the source data set). 



Three new Access Method Services commands support recoverable catalogs: 
LISTCRA, EXPORTRA, and IMPORTRA. The catalog recovery function 
alows you to repair damaged entries in a VSAM catalog when a system failure 
occurs. 



Copies of each catalog record are maintained (on the volume containing the 
catalog entry's data records) in an area called the catalog recovery area. The 
catalog recovery area is built and maintained only for recoverable catalogs, 
and is used to recover from damaged catalog entries. 



You can write an I/O error handling routine, called the exception exit routine, 
that is tailored for a cluster's or alternate index's data or index component, 
and which is called before the user program's SYNAD routine gets control. 



The KEYS and RECORDSIZE parameters of the DEFINE CLUSTER 
command have been modified so that a default value exists for them. The 
ALTER coramand's parameter set now includes the KEYS and 
RECORDSIZE parameters. 

You can import an exported object into a predefined object. 

You can specify blocksize for exported and imported objects. 

The dname subparameter of the CATALOG parameter has been omitted 
from the syntax of those commands that no longer require its specification. If 
you specify dname, it will be ignored. 
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GUIDE TO ACCESS METHOD SERVICES 



Figure 1 shows a list of tasks that Access Method Services commands can be 
used to perform. The left-hand column shows tasks that you might want to 
perform. The middle column more specifically defines the tasks. The 
right-hand column shows the commands that can be used to perform each 
task. 



Operation 

Alter 
Attach 

Backup 
Build 



Change 

Connect 
Convert 



Copy 
Create 



the information in a catalog entry 
a user catalog to the master catalog 

a VSAM data set 
• a nonVSAM data set 
a VSAM catalog 



an alternate index 

a generation data group 

Catalog a VSAM data set 

a nonVSAM data set 



Command 

ALTER 

DEFINE USERCATALOG or 
IMPORT CONNECT 

EXPORT or REPRO 

REPRO 

REPRO 

DEFINE ALTERNATEINDEX and 

BLDINDEX 

DEFINE 

GENERATIONDATAGROUP 

DEFINE CLUSTER and 
DEFINE ALTERNATE INDEX 
DEFINE NONVSAM 

ALTER 
REPRO 



a data set's description in the catalog 
the device type of the volume on 
which the catalog resides 

a user catalog to a master catalog IMPORT CONNECT 

an OS/VS CVOL to a master catalog DEFINE NONVSAM 

a data set to VSAM format REPRO 

a VSAM data set to sequential format REPRO 
OS/VS CVOL entries to VSAM CNVTCAT 

catalog entries 



a data set or catalog 

a backup copy of a data set 

a catalog 

an alias for a nonVSAM data set 

an alias for a VSAM data set 

a VSAM data set 

an alternate index 

the relationship between an alternate 
index and its base cluster 
a generation data group 

a generation data set 

a page space 

a VSAM data space 

a catalog entry for a nonVSAM 

data set 



REPRO 

REPRO or EXPORT 

DEFINE USERCATALOG 

DEFINE ALIAS 

DEFINE PATH 

DEFINE CLUSTER 

DEFINE ALTERNATEINDEX and 

BLDINDEX 

DEFINE PATH 

DEFINE 

GENERATIONDATAGROUP 
DEFINE NONVSAM 
DEFINE PAGESPACE 
DEFINE SPACE 
DEFINE NONVSAM 



Define 


(see above entries for Create) 




Delete 


a user catalog 


DELETE USERCATALOG 




an alias 


DELETE ALIAS 




an alternate index and its paths 


DELETE ALTERNATEINDEX 




a path 


DELETE PATH 




any type of catalog entry 


DELETE 




a VSAM data set 


DELETE CLUSTER 


Figure 1 (Part 1 of 3). Tasks and Commands 
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Operation 




Command 


Delete 


a VSAM data space 


DELETE SPACE 


(continued) 


a generation data group 


DELETE 
GENERATIONDATAGROUP 




a nonVSAM data set 


DELETE NONVSAM 




a page space 


DELETE PAGESPACE 


Disconnect 


a user catalog 


EXPORT DISCONNECT 


Display 


a catalog's contents 


LISTCAT 




a catalog recovery area's contents 


LISTCRA 


Enter 


a nonVSAM data set in a catalog 


DEFINE NONVSAM 


Export 


a user catalog 


EXPORT DISCONNECT 




a VSAM data set 


EXPORT or EXPORTRA 


Import 


a user catalog 


IMPORT CONNECT 




a VSAM data set 


IMPORTor IMPORTRA 


List 


a password 


LISTCAT 




t a data set's contents 


PRINT 




contents of a catalog or of a catalog 


LISTCAT 




entry 






contents of a catalog recovery area 


LISTCRA 




* tapes mounted at a checkpoint 


CHKLIST 


Load 


records into a data set 


REPRO 




an alternate index 


BLDINDEX 


Modify 


a data set's description in the catalog 


ALTER 


Move 


a catalog to another system 


EXPORT DISCONNECT and 
IMPORT CONNECT 




a VSAM data set to another system 


EXPORT and 
IMPORT 




a nonVSAM data set to another 


REPRO 




system 




Password 


establish for a VSAM data set 


DEFINE CLUSTER 


Protect 


alternate index 


DEFINE ALTERNATEINDEX 




path 


DEFINE PATH 




catalog 


DEFINE USERCATALOG or 



Print 
Recover 



page space 

modify an existing password, or add 
a password to an existing catalog 
entry * 



list passwords 
a data set 



from a processing-program failure 
from a catalog failure 



Release a user catalog from the master 

catalog 

Figure 1 (Part 2 of 3). Tasks and Commands 



DEFINE MASTERCATALOG 
DEFINE PAGESPACE 
ALTER 



LISTCAT 

PRINT 

VERIFY 
LISTCRA and 
EXPORTRA and 
IMPORTRA 
RESETCAT 

EXPORT DISCONNECT 
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Operation 

Rename 

Reproduce 

Restore 



Uncatalog 

Unload 

Verify 



a data set 

a VSAM or nonVSAM data set 

a data set's end-of-file information 
a catalog entry and/or the contents 
of its object 

a data set 

a data set or catalog 

a VSAM data set's end-of-file 



Command 

ALTER 

REPRO 

VERIFY 

EXPORTRA and 
IMPORTRA 
RESETCAT 

DELETE 

REPRO 

VERIFY 



indicators 
Figure 1 (Part 3 of 3). Tasks and Commands 
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INTRODUCTION 



Access Method Services is a service program which is used with VSAM 
(Virtual Storage Access Method) to estabUsh and maintain catalogs and data 
sets. If you plan on using VSAM, or if you are responsible for maintaining the 
system catalog, you must use Access Method Services commands. 

This chapter introduces the commands available through Access Method 
Services, provides the background information about VSAM that is required 
to establish and maintain data sets and catalogs, and briefly describes the use 
of the Time Sharing Option (TSO) with VSAM and Access Method Services. 



Access Method Services Commands 



Access Method Services enables you to define a VSAM data set and load 
records into it, convert a sequential or an indexed-sequential data set to the 
VSAM format, list VSAM catalog information or data-set records, copy a 
data set for reorganization, create a backup copy of a data set or catalog, 
convert an OS CVOL's entries to VSAM catalog entries, and make a data set 
portable from one operating system to another. 

The user invokes Access Method Services functions by issuing a command 
and specifying its parameters. The user can execute the IDCAMS program 
and include the command and its parameters as input to the program. The 
user can also call the IDCAMS program from within another program and 
pass the command and its parameters to the IDCAMS program. TSO (Time 
Sharing Option) users can execute Access Method Services functional 
commands from the TSO terminal as though they were TSO commands. 

There are Access Method Services conmiands for: 

• Defining, altering, and deleting data sets 

• Listing catalog entries 

• Copying and printing data sets 

• Constructing alternate indexes for VSAM data sets 

• Moving catalogs and data sets from one operating system to another 

• Aiding in recovery from damage to data sets or catalogs 

• Converting an OS catalog's entries to VSAM catalog entries 

• Listing tape volumes that were mounted at the time of a checkpoint 

• Controlling command execution by testing or setting condition codes 

• Establishing diagnostic-aids and printed-output options 

There are two types of Access Method Services commands: functional 
commands that are used to request the actual work — for example, defining a 
data set or listing a catalog — and modal commands that allow the conditional 
execution of functional commands. TSO users are allowed to use only the 
functional commands. 
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Functional Commands 



The functional commands are: 

• ALTER, which is used to alter previously defined catalog entries. 

• BLDINDEX, which constructs alternate indexes for existing data sets. 

• CHKLIST, which is used to identify tape volumes mounted when a 
checkpoint was taken. 

• CNVTCAT, which is used to convert entries in an OS CVOL (control 
volume) into entries in a VSAM catalog. 

• DEFINE, which is used to create catalog entries for data sets, catalogs, and 
space that VSAM is to allocate from. 

• DELETE, which is used to delete catalog entries. 

• EXPORT, which is used to create a copy of a VSAM data set for backup 
or to make a data set or user catalog portable so that it can be used on 
another system. 

• EXPORTRA, which retrieves VSAM data sets and catalog entries that are 
no longer accessible from a VSAM catalog. 

• IMPORT, which is used to read a backup copy of a VSAM data set or to 
make a data set or catalog that was previously exported from one system 
available for use in another system. 

• IMPORTRA, which returns VSAM data sets and catalog entries to an 
accessible condition. 

• LISTCAT, which is used to list catalog entries. 

• LISTCRA, which is used to diagnose suspected problems in VSAM 
catalogs. 

• PRINT, which is used to print VSAM, ISAM, or SAM data sets. 

• REPRO, which is used to copy data sets, to convert sequential and 
indexed-sequential data sets to VSAM format, to convert VSAM and 
indexed-sequential data sets to sequential format, to back up a VSAM 
catalog, to read a backup copy of a VSAM catalog, and to copy VSAM 
catalogs. 

• RESETCAT, which synchronizes a catalog to the level of its owned 
volumes. 

• VERIFY, which is used to cause a catalog to correctly reflect the end of a 
data set after an error occurred in closing a VSAM data set that may have 
caused the catalog to be incorrect. 

The functional commands that can be used on nonVSAM data sets include 
DEFINE, ALTER, DELETE, LISTCAT, CNVTCAT, REPRO, and PRINT. 

The functional commands that can be used on page spaces include DEFINE, 
DELETE, ALTER, and LISTCAT. 

All functional commands except CHKLIST can be used when you execute 
Access Method Services at a TSO terminal. 
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Modal Commands 



Language Considerations 



Parameter Set 



The modal commands, ones that control command execution and establish 
options, are: 

• IF, which tests a condition code and executes according to the results of 
the test. IF is followed by THEN and ELSE clauses which specify 
alternative actions. 

• DO-END, which denote the beginning and ending of a command 
sequence. 

• SET, which changes condition codes. 

• PARM, which specifies diagnostic-aids and printed-output options. 



All Access Method Services commands have this general structure: 

COMMAND parameters ... terminator 

COMMAND specifies the type of service requested. The parameters further 
describe the service requested. Terminator indicates the end of the command 
statement. 

Commands can begin at or to the right of the left margin. The default margins 
are 2 and 72 for batch processing jobs. Commands are separated from their 
parameters by one or more separators, that is, one or more blanks, commas, 
or comments. Comments are strings of characters surrounded by a /* and an 
*/. Comments can contain any characters you desire except an '*/'. 

Many of the commands can be abbreviated. The abbreviations that are 
allowed are hsted in the discussion of each command as well as in Appendix 
F. Restrictions that apply to abbreviations under TSO are described in "Time 
Sharing Option (TSO)." 



A parameter can be either a positional parameter or a keyword parameter. A 
positional parameter is characterized by its position in relation to other 
parameters. In Access Method Services, positional parameters are always 
required. A keyword parameter is a value preceded by a specific character 
string. For example, in: 

VOLUME (25DATA) 

VOLUME is a keyword that indicates that the value 25DATA is a volume 
serial number. 

A keyword parameter might have a set of subparameters. The subparameters 
must follow the same rules as parameter sets in general. When the 
subparameters are positional, the first subparameter is always required and 
the second may be optional (that is, you cannot specify the second 
subparameter without also specifying the first). 

Many of the keywords may be abbreviated. The abbreviations permitted are 
listed with each parameter as well as in Appendix F. Some keywords are 
plural in form; they can also be coded in the singular form. 

As a group, positional parameters must always appear first in a parameter set. 
Keyword parameters always follow any positional parameters. The order of 
keyword parameters is not important. 
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A parameter or subparameter can consist of a list of similar items. Positional 
parameter lists must be enclosed in parentheses unless the list contains only 
one item. The parentheses can be preceded and followed by blanks, commas, 
or comments. For example: 

DELETE ( entryname [...]) 

indicates that if more than one entry is to be deleted, the list of entry names 
must be enclosed in parentheses. However, if only one entryname is specified, 
the parentheses are not required. 

An item in a hst can be a parameter set itself. Each such item, as well as the 
list of items, is enclosed in parentheses. Given: 

OBJECTS (( entryname NEWNAME ( newname )) ... ) 

the following are valid: 

OBJECTS ( - 

ENTRY 1 NEWNAME ( NEWNAME 1 ) ) 

OBJECTS ( - 

( ENTRY 1 NEWNAME(NEWNAME1 ) ) - 
( ENTRY2 NEWNAME( NEWNAME2 ) ) ) 

In the first case, only one entry is to be renamed. The entryname and its new 
name are enclosed in parentheses. In the second case, each entryname and its 
new name are enclosed in parentheses and the entire list is enclosed in 
parentheses. 

All parameters and subparameters must be separated from one another by 
one or more separators (commas, blanks, or comments). The only exception 
is that parameters that immediately follow a subparameter set that is enclosed 
in parentheses do not need to be separated from the closing parenthesis. 

The values you specify in the parameters can be surrounded by separators. 
Some values can be longer than a single record. When a value is longer than a 
single record, you indicate that it is continued by coding a plus sign (+) 
followed only by blanks or a comment. The first non-separator character 
found in a record following the plus sign is treated as a continuation of the 
value. 

A value cannot contain commas, semicolons, blanks, parentheses, or slashes 
unless the entire value is enclosed in single nnotation marks. A single 
quotation mark in a field enclosed in single quotation marks must be coded as 
two single quotation marks. 

In some parameters it is necessary to specify a password following the name 
of a catalog entry or the name of a JCL DD statement. You do this by coding 
the name, a slash, and the password. The slash can be surrounded by 
separators. For example: 

DELETE PAYROLL/CTLGPAY 

specifies the password CTLGPAY for the data set PAYROLL. 

When you specify a password following a name, you must remember the 
convention for entering commands. If you code: 

MYNAME/*WORD*/ 
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Continuing Commands 



Continuation Cautions 



MYNAME is treated as a name followed by the comment WORD. If you 
want *WORD*/ to be the password, you code either: 

MYNAME/'* WORD*/' 



or 



MYNAME/ *WORD*/ 

Notice that the second example contains a blank after the first slash that 
separates the name from the password. 



Commands can be continued on several records or lines. Each record or Une 
except the last must have a hyphen or a plus sign as the last non blank 
character before or at the right margin. A hyphen indicates continuation of 
the command. A plus sign indicates continuation of the command and 
continuation of a value within the command. 

These two types of continuation are shown in the example below: 

DELETE - 
( ENTRY 1 - 
ENTRY 2 - 
ENTR+ 

Y3) - 
NONVSAM 

Blank records or records ending with complete comments must end with a 
continuation mark when they appear in the middle of a command and when 
they appear preceding or following the THEN and ELSE clauses of an IF 
command. Records ending with partial comments must always end with a 
continuation mark. Also, remember that only blank characters may appear 
between a continuation mark and the end of the record. 



The continuation rules must be used cautiously when modal commands, 
comments, or blank records appear in the input stream. Blank records or 
records ending with complete comments must end with a continuation mark 
when these types of records appear in the middle of a command or when they 
appear preceding or following the THEN and ELSE clauses of an IF 
command. Records ending with partial comments must always end with a 
continuation mark. 

You must be careful when continuing modal commands so that you don't 
inadvertently specify a null command. For information on null commands, see 
"Null Commands." 

Remember that only blanks can appear between a continuation mark and the 
end of the record. 

The following examples show common continuation errors: 

• IF LASTCC = - 
THEN 
LISTCAT 

A continuation mark (hyphen) is missing after the THEN ke5rword. A null 
command is assumed after the THEN kejnvord, and the LISTCAT 
command is unconditionally executed. 
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Terminator 



. IF LASTCC = - 
THEN - 
REPRO ... 

/♦ALTERNATE PATH*/ 
ELSE - 
PRINT . . . 

Because no continuation mark (hyphen) follows the comment, a null 
command is assumed. The ELSE keyword will not match up with the 
THEN keyword. Note the correct use of the continuation marks on the 
other records. 

. IF LASTCC = - 
THEN - 
REPRO . . . 

ELSE - 

PRINT . . . 

Because a blank line with no continuation mark (hyphen) follows the ELSE 
keyword, the ELSE becomes null and the PRINT command is unconditionally 
executed. 

. PARM TEST ( - /*COMMENT*/ 
TRACE ) 

The PARM command will not be continued onto the second record 
because characters other than blanks appear between the continuation 
mark (hyphen) and the end of the record. 

. PARM TEST ( TRA+ 

/♦FIELD CONTINUATION*/ 
CE) 

The end of the PARM command is found after the second record because 
no continuation was indicated. The command is rejected. 



The terminator indicates the end of the command. The terminator can be 
either an end of command condition (that is, no continuation mark) or a 
semicolon. If you use the semicolon as the terminator, the semicolon cannot 
be enclosed in quotation marks or embedded in a comment. Everything to the 
right of the semicolon is ignored. If there is information to the right of the 
semicolon that is continued to another record, all of the information including 
the contmued information is ignored. 

For example, if you coded: 

PARM TEST (TRACE); PARM - 
GRAPHICS (CHAIN(TN) )/*COMMENT*/ - 
PRINT . . . 
REPRO . . . 

Characters following the semicolon terminator are ignored. The continuation 
mark (hyphen) at the end of the second record causes the PRINT command 
to also be ignored. The first PARM command and the REPRO command are 
the only commands that are recognized. 
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JCL and Dynamic Allocation 



Access Method Services commands deal with both data sets and volumes 
which must be identified when used. The following is a summary of the data 
set and volume identification requirements: 

• A data set must be identified when it is actually accessed. The following 
commands require that a specific data set or data sets be identified. 

- ALTER (when altering a member name in a partitioned data set) 

- BLDINDEX 

- DELETE (when the ERASE option is invoked, when deleting a member 
of a partitioned data set) 

- EXPORT 

- IMPORT 

- PRINT 

- REPRO 

- VERIFY 

• A volume or volumes must be identified when it is necessary for VSAM to 
access the Volume Table of Contents (VTOC), allocate or release space 
using OS/VS DADSM functions, or access a catalog recovery area (see the 
section "Catalog Recovery" for information on this option). The following 
commands require volume identification: 

- ALTER (for recoverable catalogs, for VTOC access in renaming a 
nonVSAM or VSAM unique data set) 

- DEFINE (for recoverable catalogs, for space allocation in defining 
catalogs, VSAM space, and VSAM unique data sets) 

- DELETE (for recoverable catalogs, for space deallocation in deletion of 
catalogs, VSAM space, and VSAM unique data sets, for deletion of 
nonVSAM data sets) 

Other commands such as EXPORTRA, IMPORTRA, LISTCRA, and 
RESETCAT require volume identification for specific purposes. These 
requirements are covered in the discussion of each command. 

A VSAM data set or volume can be identified through JCL or by the data-set 
name or volume serial number within the command that requires the data set 
or volume for its execution. If JCL is not used, the data set or volume is 
dynamically allocated, as required. 

In order to dynamically allocate a VSAM data set, the data-set name must 
exist and be cataloged. The catalog that contains the entry must be either a 
user catalog identified with a JOBCAT or STEPCAT DD statement, a user 
catalog whose name or alias is the first qualifier of the quaUf ied data-set 
name, or the master catalog. 

In order to dynamically allocate a nonVSAM data-set, the data set name must 
exist and must be cataloged. The catalog that contains the entry must be 
either a VSAM user catalog identified with a JOBCAT or STEPCAT DD 
statement, a VSAM user catalog or OS CVOL whose name or alias is the first 
qualifier of the quaUfied data-set name, or the master catalog. 

Access Method Services dynamically allocates VSAM and nonVSAM data 
sets with a disposition of OLD. 
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When a user catalog is identified by name in an Access Method Services 
command (using the CATALOG parameter) or when VSAM determines that 
a specific user catalog must be accessed, the user catalog is dynamically 
allocated if it has not been identified with a JOBCAT or STEPCAT DD 
statement. 

In order to dynamically allocate a volume, it must already be mounted as 
permanently resident or reserved. The PRIVATE and PUBLIC use attributes 
should be carefully considered when you mount a volume. 

When a JCL DD statement is used to identify a data set, the following 
information must be included on the DD statement. 

• the data-set name 

• The unit and volume serial number(s), if the data set is not cataloged 

• The disposition 

• For VSAM data sets, the AMP='AMORG' parameter is required if the 
JCL also supphes unit and volume serial number information 

For example, the two DD statements shown below demonstrate two different 
methods by which you can describe and allocate a VSAM data set: 

//VSAMDS1 DD DSN=VSAM. DATA. SET 1 ,DISP=OLD 
//VSAMDS2 DD DSN=VSAM.DATA. SET2 , VOL=SER=VSER0 1 , 
// UNIT=3330,DISP=OLD,AMP='AMORG' 

Access Method Services does not provide specific protection for data sets in a 
shared environment. Therefore, you should specify DISP=OLD on the DD 
statement for any data set which could be accessed improperly in a shared • 
environment. 

Access Method Services uses default buffering for VSAM data sets; that is, 
the buffer space value contained in the data set's catalog entry. You may wish 
to override this value using the BUFND, BUFNI, or BUFSP subparameter of 
the AMP parameter (see OS/VS Virtual Storage Access Method (VSAM) 
Programmer's Guide for information on these parameters). 

To identify and allocate a volume, the following information must be 
included: 

• The volume serial number 

• The unit 

For example, the DD statement shown below identifies and allocates a VSAM 
volume: 

//VOLDD DD VOL=SER=VSER01 ,UNIT=3330,DISP=OLD 

Concatenated DD statements are supported under circumstances explicitly 
specified in the remainder of this publication. 

The section "JOBCAT and STEPCAT DD Statements" contains a 
description of the DD statements required for user catalogs. 

Certain Access Method Services commands use nonVSAM data sets. They 
are: EXPORT, IMPORT, EXPORTRA, and IMPORTRA. The examples 
provided for each command in the section "Command Format," as well as the 
examples in Appendix A, show the DD statements for the required nonVSAM 
data sets. 
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Output Data Sets 



If the Access Method Services processor encounters a condition which 
requires it to abort a job, it takes a snap dump of virtual storage. An 
AMSDUMP DD statement is required to obtain the snap dump; for example, 

//AMSDUMP 



DD 



SYSOUT=A 



If you do not supply an AMSDUMP DD statement and the processor 
encounters a condition requiring the job to be aborted, it produces an 
abbreviated dump only. 



The normal output data set for listing is SYSPRINT. The default parameters 
of this data set are: 

• Record format: VBA 

• Logical record length: 125, that is, 121+4 

• Blocksize: 629, that is, 5x(121+4)+4 

Print lines are 121 bytes in length. The first byte is the ANSI control 
character. The minimum specifiable LRECL is 121 (U-format records only). 
If a smaller size is specified, it is overridden to 121. 

It is possible to alter the above defaults through specification of the desired 
values in the DCB parameter of the SYSPRINT statement. The record 
format, however, cannot be specified as F or FB. If you do specify either one, 
it is changed to VBA. 

In several commands you have the option of specifying an alternate output 
data set for listing. If you do specify an alternate, you must specify DCB 
parameters in the referenced DD statement using the attributes described 
above. When specifying an alternate output data set, you should not specify F 
or FB record formats. "Appendix D: Interpreting LISTCRA Output Listings" 
shows an example of the use of an alternate output data set. 



Invoking Access Method Services 



When you want to use an Access Method Services function, you invoke the 
Access Method Services processor. The processor decodes your request (that 
is, the list of commands and parameters you supply) one command at a time, 
then calls the appropriate functional routines to perform all services required 
by that command. 

There are three ways you can invoke the Access Method Services processor: 

• As a job or jobstep 

• From a TSO terminal 

• From within your own program. (See "Appendix G: Invoking Access 
Method Services from a Problem Program.") 

If you want more details on the structure and operation of Access Method 
Services in an OS/VS2 system, see 0S/VS2 Access Method Services Logic. 
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As a Job or Jobstep 



You can use job control language (JCL) statements to invoke the Access 
Method Services processor. The examples that illustrate each command's use 
invoke the processor with JCL statements. You identify the Access Method 
Services processor with PGM=IDCAMS. 

//YOURJOB JOB YOUR INSTALLATION'S JOB=ACCOUNTING DATA 

//JOBCAT DD DSNAME=YOUR. CATALOG, DISP=SHR 

//STEP1 EXEC PGM=IDCAMS 

//STEPCAT DD DSNAME=ANOTHER. CATALOG, DISP=SHR 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

Access Method Services commands and their parameters 



//YOURJOB is required. The JOB statement describes your job to the 
OS/VS2 system. Your installation might require you to supply user 
identification, accounting, and authorization information with the JOB 
statement's parameters. 

//JOBCAT is optional. The JOBCAT DD statement identifies a user 
catalog that can be used by each of the job's steps. Because the master 
catalog is always open and available to all jobs on the system, you should 
not identify it with a JOBCAT DD statement. 

//STEPl is required (that is, an EXEC statement is required). The EXEC 
statement invokes the Access Method Services processor to decode and 
process the input statements (that is, the Access Method Services 
commands and parameters contained in the SYSIN data set). You can use 
the PARM operand of the EXEC statement to pass parameters to the 
Access Method Services processor. See the description of the PARM 
command in the chapter "Controlling Command Execution" for an 
explanation of the options you can specify. 

//STEPCAT is optional. The STEPCAT DD statement identifies a user 
catalog that can be used when processing the jobstep. If user catalogs are 
identified with JOBCAT and STEPCAT DD statements, only the 
catalog(s) identified with the STEPCAT DD statement and the master 
catalog are used with the jobstep. Because the master catalog is always 
0'^'?n 9.!id 9-Vsilablc to sll 'obs on the EVEterji you should not identify it with 
a STEPCAT DD statement. 

//SYSPRINT is required. Ihe SYSPRINT DD statement identifies the 
output device (usually a printer in a batch job) that Access Method 
Services sends messages and output information to. (See "Output Data 
Sets" for more details on how to describe an output device other than 
SYSOUT=A.) 

//SYSIN is required. The SYSIN DD statement identifies the source of the 
input statements. An input statement, to Access Method Services, is a 
functional or modal command and its parameters. When you code SYSIN 
DD *, you identify the immediately following statements as input. 

The last input statement may be followed by a delimiter statement, which 
has "/*" in the first two columns. The restrictions that apply to all Access 
Method Services commands are described in the section "Language 
Considerations," above. 
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From a TSO Terminal 



When you use the Time Sharing Option (TSO) to process your data, you can 
invoke Access Method Services from your TSO terminal. Each time you issue 
an Access Method Services command as a TSO command, TSO builds the 
appropriate interface information and invokes Access Method Services. 

You can issue one command at a time. Access Method Services processes the 
command completely before TSO allows you to continue processing. The 
following Access Method Services commands are supported in a TSO 
enviroimient: 

ALTER 
BLDINDEX 
CNVTCAT 
DEFINE - 

ALIAS 

ALTERNATEINDEX 

CLUSTER 

GENERATIONDATAGROUP 

NONVSAM 

PAGESPACE 

PATH 

SPACE 

USERCATALOG 
DELETE 
EXPORT 
EXPORTRA 
IMPORT 
IMPORTRA 
LISTCAT 
LISTCRA 
PRINT 
REPRO 
RESETCAT 
VERIFY 

The command you issue is processed immediately. You cannot issue modal 
commands (that is, the IF, THEN, ELSE, DO, END, PARM, and SET 
commands) that modify or make conditional the processing of subsequent 
functional commands. 

The restrictions that apply to the coding of Access Method Services 
commands are described in the "Language Considerations" and "Time 
Sharing Option (TSO)" sections. Other TSO restrictions are noted with the 
descriptions of each appropriate parameter. 
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From a User*s Program 



A processing program can invoke Access Method Services with the 
ATTACH, LINK or LOAD and CALL macros. Before the program issues 
the invoking macro, however, it must initialize the appropriate register and 
argument list contents. 

The register contents follow standard linkage conventions; that is, register 1 
contains the address of the argument list, register 13 contains the address of a 
save area, register 14 contains the address of the return point, and register 15 
contains the address of the entry point IDCAMS in Access Method Services. 

The contents of the argument list are described in Appendix G. 



Authorized Program Facility 



The authorized program facility (APF) limits the use of sensitive system 
services and resources to authorized system and user programs. See 
"Authorized Program Facility (APF)" in 0S/VS2 System Programming 
Library: Supervisor, for information about program authorization. 

All Access Method Services load modules are contained in SYSl.LINKLIB, 
and the root segment load module (IDCAMS) is link edited with the 
SETCODE AC(1) attribute. These two characteristics ensure that Access 
Method Services executes with APF authorization. 

APF authorization is established at the job step task level. If, during the 
execution of an APF-authorized job step, a load request is satisfied from an 
unauthorized library, the task will be abnormally terminated. It is the 
installation's responsibility to ensure that a load request cannot be satisfied 
from an unauthorized library during Access Method Services processing. 

The following situations could cause the APF authorization of Access Method 
Services to be violated: 

. An Access Method Services module is loaded from an unauthorized library. 

• A user security verification routine (USVR) is loaded from an 
unauthorized library during Access Method Services processing. 

• An Exception Exit routine is loaded from an unauthorized library during 

Access I'l'fsthod Services tjrO' 



• A user-supplied special graphics table is loaded from an unauthorized 
library during Access Method Services processing. 

Since APF authorization is established at the job step task level, Access 
Method Services will not be authorized if invoked by an unauthorized 
problem program or an unauthorized Terminal Monitor Program (TMP). 

Under TSO, if your system has neither OS/VS2 TSO/VTAM Selectable Unit 
(VS2.03.813) or the OS/VS2 MVS TSO Command Package Program 
Product, you can authorize your TMP by re-link editing it with the 
SETCODE AC(1) attribute. With either the OS/VS2 TSO/VTAM 
Selectable Unit or the OS/VS2 MVS TSO Command Package Program 
Product you must enter the names of those Access Method Services 
commands requiring APF authorization which you wish to execute under TSO 
in the authorized command list. If you have the OS/VS2 TSO/VTAM 
Selectable Unit, see 0S/VS2 System Programming Library: TSO for 
information on how to enter the command names in the list. If you have the 
OS/VS2 MVS TSO Command Package Program Product, see 0S/VS2 MVS 
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TSO Command Package: User's Guide and Reference for the same 
information. 

The restricted functions performed by Access Method Services that cannot be 
requested in an unauthorized state are: 

• REPRO — the copy catalog facility, or the catalog unload/reload facility. 

• PRINT — when the object to be printed is a VSAM catalog. 
. LISTCRA 

. EXPORTRA 

. RESETCAT 

If the above functions are required and Access Method Services is invoked 
from a problem program or a TSO Terminal Monitor Program, the invoking 
program must be authorized. 



VSAM Data Sets 



You need to know about the structure and treatment of VSAM data sets to 
use Access Method Services. VSAM data can be stored in key sequence, 
entry sequence, or record-number sequence. 

Records in a key-sequenced data set are stored in the order defined by the 
collating sequence of the contents of the key field in each record. Each record 
has a unique value^ such as employee number or invoice number, in the key 
field. To determine where to insert a new record, VSAM uses an index that 
pairs the key of a record with the record's location. 

Records in an entry-sequenced data set are stored without respect to the 
/ . contents of the records. Their sequence is determined by the order in which 

they are stored: their entry sequence. A new record is stored after the last 
record in the data set. 

Records in a relative-record data set are stored without respect to their 
contents and to their sequence of entry. Their sequence is determined by the 
user-specified record number that identifies the record's position in the data 
set. Each record is fixed-length and is stored in a slot. Records can be inserted 
between other records (that is, in an empty slot between two filled slots), can 
be added to the end of the data set, or can replace records within the data set. 

When a data set is created, it is defined, along with its index, if any, in a 
cluster. A key-sequenced data set and its index make up a cluster. An 
entry-sequenced or relative record data set is also defined as a cluster, even 
though it does not have an index. 

Apart from the primary index, one or more alternate indexes can be built over 
a single key-sequenced or entry-sequenced data set. Each alternate index 
accesses the data records of a given data set via a different key field (the 
alternate key) within these records. A VSAM cluster that contains data 
records pointed to by an alternate index is called a base cluster. 

In order to gain access to a base cluster via an alternate index, you must 
define a path between the alternate index and the base cluster. When a path 
is defined, you must specify the name of the alternate index which is to be 
considered as the entry for the path. The termination of the path is the base 
cluster to which the alternate index is related. The path, which is an entry in 

|\ the catalog, has a name of its own which always refers to the alternate index 

y and the related base cluster as a pair. 
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VSAM Volume Ownership 



In addition to data sets, VSAM accesses catalogs. All data — ordinary user 
data, indexes, and catalogs — is physically stored and manipulated in the same 
way. 

Refer to Planning for Enhanced VSAM Under OS/VS for more 
information on the structure of VSAM data sets and how data is physically 
stored. 



VSAM gets and manages space on a storage volume in units called data 
spaces. One or more data sets are stored in a data space. Conversely, a data • 
set may be stored in one or more data spaces, on one or more storage 
volumes. Data sets and data spaces may be extended beyond their original 
size. Data spaces are extended by whole numbers of tracks or cylinders; 
VSAM extends them automatically as more space is needed. A data space can 
be as large as a volume and can have a maximum of 16 extents. 

VSAM data spaces are defined in a VSAM catalog. That catalog controls 
(owns) the volumes that contain the data spaces defined in the catalog, 
including the volume that contains the catalog itself. The catalog also owns 
candidate volumes for VSAM data sets defined in the catalog. VSAM 
ownership of a volume is established with the DEFINE USERCATALOG or 
DEFINE SPACE commands or when the UNIQUE attribute is specified with 
DEFINE CLUSTER, DEFINE ALTERNATEINDEX, or DEFINE 
PAGESPACE. 

All VSAM clusters, alternate indexes, page spaces, and data spaces stored on 
a volume must be cataloged in the catalog that owns the volume. On the other 
hand, nonVSAM data sets can be cataloged in any VSAM catalog. 

VSAM's ownership and usage of space on a volume is indicated in the 
volume's table of contents (that is, in DSCBs in the volume's VTOC). Two 
data-set security bits in the format- 1 (Identifier) DSCB of each VSAM data 
space on the volume are set to indicate that a password is required to read or 
write data in the data space. (They are set whether the object or objects in the 
data space are actually password-protected or not.) The ownership bit in the 
volume's format-4 (VTOC) DSCB is set to 1. The ownership bit indicates 
that the volume is owned by a VSAM catalog, but does not identify the 
owninp rataloc F.nrh VSAM catalog contains a volume entrj' for each volume 
it owns. The volume entry describes the volume's characteristics, each extent 
of the volume's VSAM data space(s), and each VSAM ohiect that uses the 
volume's space. 

In order to take away the ownership of a volume from a VSAM catalog, you 
must first delete all VSAM objects and then all data spaces on the volume. 
The DELETE SPACE command deletes the VSAM data spaces on the 
volume, removes the volume entry from the catalog, and revises the format-4 
DSCB in the volume's VTOC. When you are unable to use the DELETE 
command because Access Method Services can no longer access the volume 
(due to damage that resulted from a system or hardware failure), you can 
reset the ownership bit by using the ALTER REMOVEVOLUMES command 
(see "Modifying Catalog Information"). 

The VTOC contains the name of each VSAM data space on the volume, and 
might contain VSAM-generated names for the data and index components of 
a cluster, alternate index, or page space. When you name the data or index 
component of a VSAM data set, alternate index, or page space, and when the 
object or its component is in its own data space (that is, it was defined with 
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the UNIQUE attribute), the name of the component identifies the data space. 
Otherwise, VSAM generates a name for the data space. The name generated 
by VSAM has the following format: 

• For a data space containing suballocated VSAM objects, the VSAM 
generated name is: 

Z999999n.VSAMDSPC.Taaaaaaa.Tbbbbbbb 

where: 

- n=2 if no catalog resides in the data space 

- n=4 if a user catalog resides in the data space, or if the master catalog 
resides in the data space and the master catalog was created under 
OS/VS2 Release 2 or a later release 

- n=6 if the master catalog resides in the data space 

- aaaaaaabbbbbbb is the timestamp value 

• For a unique data space (that is, a data space that cannot contain more 
than one cataloged VSAM object), the VSAM-generated name is: 

VSAMDSET.Tbbbbbbb.DFDyyddd.Taaaaaaa.Tbbbbbbb 
where: 

- yyddd is the date (year and Julian day) 

- aaaaaaabbbbbbb is the timestamp value 

When you define a VSAM data set with the UNIQUE attribute, VSAM 
creates a unique data space. If you specify a name for the data and/or index 
component, VSAM places the name you specify in the format- 1 DSCB rather 
than generating a name. 

If you do not specify a name for the data and index components of a 
suballocated VSAM data set (that is, a data set which shares a data space 
with other VSAM data sets), VSAM generates a name for these components. 
The format of the VSAM-generated name is the same as that shown above 
for a unique data space. 

To relate the VSAM-generated name with a VSAM cluster, alternate index, 
page space, catalog, or data space, you list the catalog that owns the volume. 
You issue a LISTCAT command to list the catalog's contents. The LISTCAT 
output listing relates the VSAM-generated names with user-assigned 
entrynames for cataloged objects. 

Each volume owned by a VSAM catalog contains two timestamps that are 
written in the VTOC when the volume is first cataloged. Both timestamps are 
updated but only one (the second) is checked. The first is maintained for 
compatibility with earlier VSAM releases. The volume timestamps are 
updated as follows: 

• For a volume owned by a recoverable VSAM catalog, each time the 
catalog's Volume record is modified. 

• For a volume owned by a nonrecoverable VSAM catalog, each time space 
is allocated, extended or scratched by VSAM. When the volume is 
mounted, the system compares the second timestamp on the volume to the 
timestamp in the catalog owning the volume. If the volume's timestamp is 
earlier than the catalog's timestamp, the volume is considered down-level. 
Access Method Services will not normally open a data set on a down-level 
volume. 
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Some of the implications of VSAM volume ownership are: 

• All VSAM clusters, alternate indexes, page spaces, and data spaces on a 
volume must be cataloged in the catalog that owns the volume. Only one 
VSAM catalog can own the volume. 

• VSAM volume ownership does not affect nonVSAM data sets that reside 
on the volume. NonVSAM data sets can exist on a volume owned by a 
VSAM catalog, and can (but should not) be cataloged in a catalog that 
does not own the volume. Since OS control volumes (CVOLs) are 
considered nonVSAM data sets, an OS CVOL can also exist on a volume 
owned by a VSAM catalog. 

• In order to release a volume from ownership by a VSAM catalog, you must 
delete all VSAM objects that reside on the volume. The catalog also 
contains a volume entry which describes the volume and its VSAM data 
spaces. After deleting the VSAM objects, you issue the DELETE SPACE 
command. The DELETE SPACE command deletes the VSAM data spaces 
on the volume, removes the volume entry from the catalog, and revises the 
format- 1 and format-4 DSCBs in the volume's VTOC. You can delete all 
VSAM data spaces on a volume whether or not they contain VSAM 
objects by specifying the FORCE option on the DELETE SPACE 
command. 

• A user catalog cannot exist on a volume that contains active page spaces, 
paging data sets (that is, system data sets that are paged into and out of the 
CPU's virtual storage), or the SYSl.STGINDEX. These objects are 
cataloged in the master catalog and, therefore, the volume(s) on which 
they reside are owned by the master catalog. 



VSAM's Use of Catalogs 



Most uses of Access Method Services involve doing something to the VSAM 
catalogs. For example, establishing a VSAM data set involves creating an 
entry in a catalog; deleting a VSAM data set involves removing an entry from 
the catalog; and moving a VSAM data set from one system to another 
involves moving an entry from a VSAM catalog in one system to a VSAM 
catalog in another system. The use of Access Method Services with VSAM 
requires an understanding of how VSAM uses catalogs. 

VSAM uses catalogs as a central information point for all VSAM data sets 
and the direct-access storage volumes on which they are stored. There are two 
kinds of VSAM catalogs: master catalogs and user catalogs. In addition, OS 
CVOLs (control volumes) can be attached to a VSAM master catalog. In a 
VS2 system, the VSAM master catalog is the system's primary catalog and is 
required. Any number of VSAM user catalogs are optional. The system's 
nucleus contains a pointer to the VSAM master catalog, which in turn points 
with catalog connector entries to any VSAM user catalogs. The OS CVOLs 
are cataloged in the master catalog as nonVSAM data sets with the name 
"SYSCTLG.ca/«awe." 

Catalogs provide VSAM with the information to allocate space for data sets, 
verify authorization to gain access to them, compile usage statistics on them, 
and relate RBAs to physical locations. 

For a VSAM data set to exist, it must be defined in a VSAM catalog. That is, 
you must enter in the catalog a data set's name and other facts about it by 
using Access Method Services to define it. 
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The Master Catalog 



All VSAM data sets on a volume must be cataloged in the same catalog, 
either the master catalog or a user catalog. A data set is defined in only one 
catalog. VSAM "ownership" of a volume by a catalog is established the first 
time VSAM space is allocated on that volume. The DEFINE with the 
UNIQUE attribute (of a cluster, alternate index, or page space), DEFINE 
USERCATALOG, or DEFINE SPACE commands establish such ownership. 
All subsequent VSAM data sets defined on the volume are required to be 
defined in the same catalog (that is, the catalog that owns the volume). 

When you execute a program to process a data set, catalogs are searched to 
find out which volume(s) the data set is stored on, unless you give volume 
serial number(s) by way of JCL. 

The order in which catalogs are searched depends on whether catalogs are 
specified for the current job step (STEPCAT) or job (JOBCAT), whether the 
name of the data set is a qualified entry name, and on whether the catalog is to 
be used to define a new entry or searched for existing entries. See "Order of 
Catalog Use" for an explanation of how a catalog is selected during the 
processing of an Access Method Services command. ("Order of Catalog Use" 
sections appear in the chapters that describe each of the following commands: 
DEFINE, BLDINDEX, ALTER, LISTCAT, and DELETE.) 

Note: An unqualified name and a qualified name cannot exist in the same 
catalog if the first qualifier of the qualified name is the same as the 
unqualified name. For example, DATA and DATA.PAYROLL cannot exist 
in the same catalog. 

Figure 2 illustrates how data sets in a VS2 system can be divided up for 
cataloging among the VSAM master catalog, VSAM user catalogs, and OS 
control volume catalogs (CVOLs). 

If you need information on the structure of a VSAM catalog or more details 
on the information contained in the catalog, refer to Planning for Enhanced 
VSAM Under OS /VS. 



In an OS/VS2 system, the VSAM master catalog is the system's primary 
catalog. When you generate the system (that is, when you use the SYSGEN 
procedure), you define the system's master catalog during the first step in 
stage 2 of SYSGEN. The name you specify for the catalog must be different 
from the name of the master catalog of the driving system. See 0S/VS2 
System Programming Library: System Generation Reference for details on 
the system generation process. 

The master catalog does not have to reside on the IPL volume. The 
SYSCTLG member of SYSl. NUCLEUS, a nonVSAM data set on the IPL 
volume, points to the volume containing the master catalog. The SYSCTLG 
member is referenced during IPL and NIP processing. It is recommended that 
the master catalog and VSAM objects cataloged in it not reside on the IPL 
volume — if the master catalog has to be recovered, then restoring the master 
catalog will not affect the IPL volume. 

The master catalog is the only catalog referenced during NIP processing. 
Therefore, all system data sets, data sets entered in LNKLSTxx, paging data 
sets, and libraries specified in the JES start procedure must be cataloged in 
the master catalog, and not in a user catalog or an OS control volume 
(CVOL). 
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Figure 2. Catalog Relationships in an 0S/VS2 System 



You cannot move the master catalog from one system to another by using the 
EXPORT and IMPORT commands. You can, however, use the REPRO 
command to make a copy of the master catalog, then move the copy to 
another system. If your master catalog is recoverable, you can use the 
LISTCRA, EXPORTRA, IMPORTRA, and RESETCAT commands to repair 
damaged entries that result from system failure. 



"Appendix H: Changing the Attributes of the VSAM Master Catalog" 
describes how you can create a new master catalog for your system. This 
procedure assumes that you already have a valid master catalog with which to 
IPL your system. If your master catalog has somehow been destroyed, you 
can create a new one on another system using the appropriate portion of the 
same procedure described in Appendix H. 

A master catalog cannot be used simultaneously as the VSAM master catalog 
for two OS/VS2 systems (that is, the master catalog cannot be shared 
between two systems as each system's master catalog). However, one 
system's master catalog can be used as a user catalog on another OS/VS2 
system that includes VSAM when the catalog is on a shared direct-access 
device. When a catalog is used simultaneously by two or more systems, all of 
the catalog's volumes must be on shared direct-access devices. If you do this, 
take care to assign passwords to each of the catalog's page spaces and system 
data sets to prevent their accidental or unauthorized use. 
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Transporting User Catalogs 



You can move a user catalog to another system that includes VSAM (that is, 
to an OS/VSl or OS/VS2 system or to a DOS/VS system) to make the 
objects cataloged in the user catalog available to the other system. The user 
catalog might own only the volume on which it resides. In this case, the 
volume can be moved as a single unit to another system. When the catalog 
owns more than one volume, either all volumes owned by the catalog must be 
moved to the other system or the catalog's ownership of the volumes that are 
not moved must be taken away before the catalog is moved. 

You can use the EXPORT command with the DISCONNECT parameter to 
remove a user catalog from its OS/VS system. The EXPORT command 
deletes the user catalog's connector entry in the master catalog. The catalog, 
its cataloged objects, and its volume(s) become unavailable to the old system. 

You use the IMPORT command with the CONNECT option to make the 
exported catalog available to the new OS/VSl, OS/VS2, or DOS/VS system. 
The IMPORT command builds a connector entry in the master catalog that 
identifies the user catalog's volume. 



JOBCAT and STEPCAT DD Statements 



/ 



User catalogs can be dynamically allocated. User catalogs can also be 
allocated directly, by using a JOBCAT or STEPCAT DD statement. A 
previous section, "JCL and Dynamic Allocation," discusses dynamic 
allocation of catalogs and cataloged objects. 

You can specify a catalog that is to be available for use only with a job step, 
or that is to be available for the entire job. A STEPCAT DD statement 
identifies a catalog that is available for a single job step; a JOBCAT DD 
statement identifies a catalog that is available during the entire job. When 
both JOBCAT and STEPCAT catalogs are specified, the user catalog 
specified by STEPCAT is used for the job step. The JOBCAT and STEPCAT 
statements you code should be in the form: 

//JOBCAT DD DISP= { OLD I SHR } , 

// DSNAME= usercatalogname 

and 

//STEPCAT DD DISP= { OLD | SHR } , 

// DSNAME= usercatalogname 

Because the master catalog contains information about each user catalog, you 
do not need to specify the catalog's volume and device information. 

You can specify more than one user catalog for a job or job step. To indicate 
another user catalog, follow the JOBCAT or STEPCAT DD statement with a 
concatenated DD statement — an unlabeled DD statement that specifies the 
name of another user catalog: 

//STEPCAT DD DISP=SHR,DSN=MGMTCAT1 
// DD DISP=SHR,DSN=MGMTCAT2 

You can supply a JOBCAT or STEPCAT DD statement to allocate the 
catalog when: 

• Your job processes a user catalog (that is, when your sequence of Access 
Method Services commands adds, modifies, lists, or deletes a VSAM 
catalog entry) 



Introduction 47 



• Your job includes a space allocation request directed toward a volume that 
contains VSAM data spaces (that is, a DEFINE SPACE or DELETE 
SPACE command) 

• Your job causes a VSAM data set to be opened and that data set is defined 
in a user catalog (that is, a REPRO or PRINT of a VSAM data set, a 
DELETE with the ERASE option, EXPORT, IMPORT, IMPORTRA, 
BLDINDEX, or VERIFY) 

The description of each of the commands that adds, modifies, lists, or deletes 
VSAM catalog entries contains a section, "Order of Catalog Use," which 
explains how VSAM selects a catalog for use by a particular job. 

You must supply either a JOBCAT or STEPCAT DD statement to allocate 
the catalog when: 

• Your job uses lEHDASDR to dump a volume owned by a user catalog 

• Your job causes the catalog to be opened as a data set (for example, using 
the PRINT command to print a catalog, using the LISTCRA command 
with the COMPARE option) 

You can minimize the use of JOBCAT and STEPCAT DD statements for 
your jobs when you name your data set with a qualified entryname whose 
first qualifier is the name or alias of the catalog in which the data set is 
defined. When the catalog is not identified with a JOBCAT or STEPCAT DD 
statement or explicitly named (that is, with an Access Method Services 
command's CATALOG parameter), the OS/VS scheduler searches the 
master catalog for the data set's entryname. If the entryname is not found, the 
system uses the entryname 's first qualifier as a search argument and attempts 
to locate either a user-catalog connector entry or a user catalog's alias entry. 
If the system finds a user-catalog connector entry (that is, an entry whose 
name or alias is the same as the entryname's first qualifier), the system 
searches that user catalog for the data set's entry, using the data set's full 
entryname. 



OS Control Volumes (CVOLs) 



In addition to the VSAM master catalog, your system can include user (or 
private VSAM) catalogs and OS control volumes (CVOLs or private OS 
catalogs). The system's catalog stmrtiire can be organizsd v/ith a mastei 
catalog only, or with a master catalog and any combination of one or more 
user catalogs and/or OS CVOLs. 

The master catalog (the primary level) points to each user catalog and OS 
CVOL in the system. A VSAM user catalog, cannot be accessed via another 
user catalog or OS CVOL. 

The VSAM master catalog provides the following benefits in your OS/VS2 
system: 

• Portability of catalogs between systems 

• The capability of mounting, as needed, the volumes containing catalogs 

• Minimization of the effect of errors or damaged entries on a catalog 

• Performance improvements by reducing contention for a catalog 
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The following differences between VSAM user catalogs and OS CVOLs 
might affect your choice of having user catalogs or OS CVOLs on your 
system: 

• You cannot catalog VSAM objects in an OS CVOL. 

• You cannot use Access Method Services commands to catalog objects in, 
or modify existing entries of, an OS CVOL. 

• You can convert an OS CVOL's entries to VSAM catalog entries when 
you use the CNVTCAT command, but there is no corresponding facility to 
convert VSAM catalog entries to OS CVOL entries. 

• A user catalog requires at least twice as much space as a corresponding OS 
CVOL. 

• User catalogs can be moved only to other OS/VS systems that include 
VSAM. OS CVOLs can be moved to MVT and OS/VS2 systems that 
might not include VSAM. 

You can use the DEFINE NONVSAM command to define a CVOL (as 
though it were a nonVSAM data set) in the master catalog when you name it 
SYSCTLG.quaUfier. You can't use lEHPROGM to create or extend a CVOL. 

Many users choose to use OS CVOLs initially, then convert the CVOLs to 
user catalogs when their system is running smoothly. Whether you use an OS 
CVOL or a user catalog, nonVSAM data sets are cataloged and uncataloged 
by your specification of the DD statement's DISP parameter (see OS/VS 2 
JCL for more details on DD statements and job control language). VSAM 
objects are cataloged and uncataloged in VSAM catalogs by using Access 
Method Services conmiands. 



Time Sharing Option (TSO) 



TSO is a subsystem of OS/VS2 that'provides conversational time sharing 
from remote terminals. You can use TSO with VSAM and Access Method 
Services to: ^. 

• Execute Access Method Services commands 

• Execute a program to call Access Method Services 

When TSO is used with Access Method Services, the following differences 
must be observed: 

• TSO allows the initial characters of a keyword to be supplied as an 
abbreviation of the keyword. The only restriction is that enough initial 
characters must be suppUed to make the keyword unique. TRACKS, for 
example, could be abbreviated TR, TRA, or TRAC, because no other 
keyword within the same command can be abbreviated in the same way. 

Some abbreviations which are acceptable to Access Method Services such 
as CYL, CYLINDER, REC, RECORD cannot be used under TSO 
because the abbreviations do not contain enough initial characters to make 
the keyword unique. TSO can't tell whether you mean CYLINDERS or 
CYLINDERFAULT when CYL or CYLINDER is used. Similarly, 
abbreviations REC and RECORD are ambiguous; TSO doesn't know if 
you mean RECORDS or RECORDSIZE. 

• In addition, the abbreviations described in the remainder of this publication 
(for example, TRK for TRACKS) are acceptable to TSO. 
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• When a parameter's value consists of a list of one or more parenthesized 
parameter sets, the outer parentheses surrounding the list are always 
required. For example, if lowkey and highkey form a parameter set that 
can be repeated several thnes, then the outer parentheses are required even 
when just one parameter set is specified; as foUows: 

KEYWORD(( lowkey highkey )) 

• A name can be specified in quotation marks or not in quotation marks. 
Under TSO, however, a prefix (for example, the userid) is added to a name 
that is not in quotation marks. The prefix becomes the first qualifier in the 
name. If the name is a volume serial number (as it may be in the DELETE 
command, for example), enclose it in quotation marks; if you do not, a 
prefix is added to the volume serial number. 

• Under TSO, a volume serial number can consist of alphabetic, national, 
numeric, or special (hyphen only) characters; if any other characters are 
used, the volume serial number cannot be used as an entryname under 
TSO. 

• Under TSO, a password can be supphed with any entryname; the password 
is ignored if not required. 

Note: At a TSO terminal, the logon password is checked first before the 
user is prompted to supply a password for a cluster. Checking the logon 
password counts as one attempt to obtain a password. If the user has not 
specified ATTEMPTS in his DEFINE command, he has one attempt to 
supply the catalog's password because the default is two. 

• The modal commands, used to control execution (IF-THEN-ELSE 
command sequence, DO-END command sequence, SET, and PARM), are 
not allowed under TSO. 

• Under TSO, the user is prompted to complete a fully-qualified name. The 
user is also prompted to supply required, but omitted, parameters. 

For details about the format of a displayed catalog entry (resulting from a 
LISTCAT command) for a TSO user, see "Appendix B: Interpreting 
LISTCAT Output Listings." 

For details about writing and executing programs and allocating data sets with 
TSO, see 0S/VS2 TSO Terminal User's Guide and OS/VS2 TSiO 
Command Language Reference. 



50 OS/VS2 Access Method Services 



Mass Storage System (MSS) 



The IBM 3850 Mass Storage System can be used with OS/VS2 to store a 
massive amount of data onUne to the operating system. It is described in the 
Introduction to the IBM 3850 Mass Storage System (MSS). 

When you have the Mass Storage System, you can define VSAM data spaces, 
user catalogs, and data sets and nonVSAM data sets on mass-storage 
volumes. The master catalog cannot be stored on a mass-storage volume. 

A VSAM catalog may have defined in it both objects stored on direct-access 
storage volumes and objects stored on mass-storage volumes. In particular, 
the data component of a key-sequenced cluster may be stored on a 
mass-storage volume and the index component on a direct-access storage 
volume, or vice versa. 

Space for an object larger than one cylinder that is stored on a mass-storage 
volume should be allocated in cylinders to optimize data transfer (staging and 
destaging) between mass-storage and direct-access storage. 

Data stored in the Mass Storage System is staged from mass storage to a 
direct-access storage staging drive when the object to which the data belongs 
is opened or when the data is requested. It is destaged from the staging drive 
to mass-storage when the object is closed. (The Introduction to the IBM 
3850 Mass Storage System (MSS) tells what direct-access storage devices 
can be used for staging.) 

Access Method Services for the Mass Storage System provides a set of 
commands for the management of mass-storage volumes. These commands 
are described in OS/ VS Mass Storage System (MSS) Services: Reference 
Information. 

Access Method Services for managing VSAM catalogs provides parameters 
for options of the Mass Storage System in the DEFINE and ALTER 
commands, which enable you to specify how a VSAM data set that is stored 
on a mass-storage volume is to be staged and destaged and how a user catalog 
that is stored on a mass-storage volume is to be destaged. These parameters 
are described in this book. 

The staging attributes, BIND, CYLINDERFAULT, and STAGE, affect 
performance. BIND causes an object to be staged when it is opened and to be 
retained (bound) in direct-access storage. CYLINDERFAULT causes 
portions of an object to be staged only as needed during processing. STAGE 
is a compromise: the object is staged when it is opened, but not retained in 
direct-access storage. When the staging activity of other objects is Ught, 
STAGE can achieve results similar to BIND: the data might remain in 
direct-access storage, available for requests for access without staging. When 
the staging activity of other objects is heavy, STAGE can achieve results 
similar to CYLINDERFAULT: the data might not remain in direct-access 
storage and might have to be restaged when needed. 

A user catalog that is stored on a mass-storage volume is always staged and 
bound when it is opened — that is, it is retained in direct-access storage until it 
is closed. Not binding a user catalog might degrade performance. 

The destaging attributes, DESTAGEWAIT and NODESTAGEWAIT, affect 
data integrity. DESTAGEWAIT causes VSAM to return control to the 
program that closes an object synchronously— only after destaging is 
complete. VSAM can notify the program whether destaging was successful. 
NODESTAGEWAIT causes VSAM to return control to the program 
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asynchronously — as soon as the object is closed, but before it has been 
destaged. 

A failure in destaging causes a message to be written to the operator. With 
DESTAGEWAIT, an error code is also returned from CLOSE to the 
processing program. But there are no recovery procedures for a program to 
undertake: one use of DESTAGEWAIT is for a processing program to 
periodically issue a temporary CLOSE of a bound object to cause it to be 
destaged at various checkpoints. The processing program can terminate 
processing if a failure occurs in destaging. The last copy destaged would be 
the copy to fall back to, pending correction of the error that caused the 
failure. 

A data component that is defined with the ERASE parameter and stored on a 
mass-storage volume, is overwritten with binary zeros on the staging drive 
after it is destaged. 



52 OS/VS2 Access Method Services 



DATA SECURITY AND PROTECTION 



Data-Set Security 



The protection of data includes data security, or the safety of data from theft 
or intentional destruction, and data integrity, or the safety of data from 
accidental loss or destruction. Security and integrity options are specified by 
an entry in the DEFINE command. 



Access Method Services provides options to protect data sets against 
unauthorized use and loss of data. To effectively use the protection features, 
you must understand the difference between two different operations: 1) 
referring to a catalog entry and 2) using the data set represented by a catalog 
entry. A catalog entry is referred to when new entries are defined (DEFINE), 
or old entries are altered (ALTER), deleted (DELETE), or listed 
(LISTCAT). The data set represented by the catalog entry is used when it is 
connected to a user's program (OPEN), or disconnected (CLOSE), or when 
it reaches its upper RBA-boundary (End-of- Volume). The distinction 
between these two operations is the key to understanding how the VSAM 
passwords work; different passwords may be needed for the two operations. 

The data-set security options are described in the sections that follow. 



Passwords to Authorize Access 



You can optionally define passwords for clusters, cluster components (data 
and index), page spaces, alternate indexes, alternate index components (data 
and index), paths, and VSAM catalogs, which a person must give to get 
permission to gain access to them. There are different passwords for various 
degrees of security. The higher levels provide greater protection than the 
lower levels. The levels are: 

• Full access. This is the master password, which allows you to perform aU 
operations (retrieving, updating, inserting, and deleting) on a data set and 
any index and catalog record associated with it. Using this password to 
gain access allows you to delete an entire VSAM data set and to alter any 
catalog information (including passwords) about the data set, index, or 
catalog, except the cataloged object's physical-extent descriptors. The 
master password allows all operations and bypasses any additional 
verification checking by the user-security-verification routine. 

• Control access. This password authorizes you to use control-interval 
access. See OS/VS Virtual Storage Access Method (VSAM) Options for 
Advanced Applications for information on the use of control-interval 
access. 

• Update access. This password authorizes you to retrieve, update, insert, or 
delete records in a data set. Specifying a catalog's update password 
authorizes you to define data sets in it, and to alter or delete nonVS AM 
and GDG entries in it. 

• Read access. This is the read-only password, which allows you to examine 
data records and catalog records, but not to add, alter, or delete them, nor 
to see password information in a catalog record. 

If you define passwords for any data sets in a catalog, you must also define 
passwords for the catalog in order for the data-set passwords to have effect. If 
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you do not define passwords for the catalog, no password checking will take 
place during operations on the data set's catalog entries. 

Operations on a catalog may be authorized by the catalog's appropriate 
password or, in some cases, by the appropriate password of the data set 
whose definition in the catalog is being operated on. For example, defining a 
data set in a password-protected catalog requires the catalog's update (or 
higher) password. Listing or deleting a definition requires the appropriate 
password of either the catalog or the data set. However, if the catalog, but not 
the data set, is protected, you need give no password to list the data set's 
catalog definition. 

Because a user catalog defines itself, it may be password-protected without 
the master-catalog being password-protected. To delete a user catalog, you 
must give its master password, whether the master catalog is 
password-protected or not. 

Each higher level password allows all operations permitted by lower levels. 
Any level may be null (not specified), but if a low-level password is specified, 
the master level password must also exist. The DEFINE and ALTER 
commands accomplish this by giving all of the higher passwords the value of 
the highest password specified. Thus, if you specify only a read-level 
password, that password will become the update-, control-, and master-level 
password as well. If you specify a read password and a password, the 
control-password value will become the master-level password as well. 
However, the update-level password will be null. 

One reason for password-protecting the components of a cluster is to prevent 
access to the index of a key-sequenced data set, since the only way to gain 
access to an index is to open it independently of the cluster. (See OS/VS 
Virtual Storage Access Method (VSAM) Options for Advanced Applications 
for a description of access to an index.) 

Some Access Method Services operations may involve more than one 
password authorization. For example, importing a data set involves defining 
the data set and loading records into it. If the catalog into which the data set 
is being imported is password-protected, its update- (or higher-level) 
password is required for the definition; if the data set is password-protected, 
its update- (or higher-level) password is required for the load. The IMPORT 
and IMPORTRA commands allow you to specify the password of the catalog; 
the passwuiu, if any, of the data set being imported is obtained by the 
commands from the exported data. 

Every VSAM data set is represented in the VSAM catalog by two or more 
entries: a cluster entry and a data entry, or, if the data set is a key-sequenced 
data set, a cluster entry, a data entry, and an index entry. Of the two or three 
entries, the cluster entry is the controlling entry. Each of the two or three 
entries can have its own set of four passwords; the passwords you assign have 
no relationship to each other. For example, if you password-protect a cluster 
but don't password-protect the cluster's data component, someone could issue 
LISTCAT to determine the name of your cluster's data component, then open 
the data component and access records in it — even though the cluster itself is 
password protected. 

Catalogs are themselves VSAM data sets, and may have passwords. For some 
operations (for example, listing all of a catalog's entries with their passwords 
or deleting catalog entries), the catalog's passwords may be used instead of 
the entry's passwords. Thus, if the master catalog is protected, the update- or 
higher-level password is required when defining a user catalog. This is 
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because all user catalogs have an entry in the master catalog. When deleting a 
protected user catalog, the user catalog's master password must be specified. 

The following protection considerations and precautions should be observed 
when using commands which refer to the VSAM catalog: 

• To create a catalog entry (with the DEFINE command), the update- or 
higher-level password of the catalog is required. 

• To modify a catalog entry (with the ALTER command), the master 
password of the entry or the master password of the catalog which contains 
the entry is required. However, if the entry to be modified is a nonVSAM 
or GDG entry, the update-level password of the catalog is sufficient. 

• To gain access to passwords in a catalog (for example, to list or change 
passwords), you must specify the master-level password of either the entry 
or the catalog. Similarly, a master-level password must be specified with 
the DEFINE command if you want to model an entry's passwords. 

• To delete a protected data-set entry from a VSAM catalog requires the 
master-level password of the entry or the master-level password of the 
catalog containing the entry. However, if the entry describes a VSAM data 
space, the update-level password of the catalog is sufficient. If the entry to 
be deleted is a nonVSAM, GDG, or alias entry, the update level password 
of the catalog is sufficient. 

• If the password of the catalog is the read-level, catalog entries with the 
read-level passwords may be listed by specifying the read password of the 
entry or the catalog's read level password. However, entries without 
passwords may be listed without specifying the catalog's read-level 
password. If you wish to list the passwords associated with a catalog entry, 
you must specify the master password of the entry or the catalog's master 
password. 

• If the proper password is not specified with the Access Method Services 
command, a password prompt will occur. Unless you have specified the 
CODE parameter on either the DEFINE or ALTER command, the prompt 
will include the name of the data set; if you have specified CODE, the 
prompt will include the code name you specified. In some circumstances, 
due to the manner in which catalog entries are ref erence4, more than one 
prompt may occur. For example, when an ALTER or DELETE request is 
processed, the catalog must be referred to twice, once to locate the 
information, and once to perform the requested function. Again, incorrect 
password specification when listing catalog entries may cause numerous 
prompts. To avoid unnecessary prompts, specify the catalog's password, 
which allows access to all entries that the operation affects. A catalog's 
master-level password will allow you to refer to all catalog entries. 
However, a protected cluster cannot be processed with the catalog's master 
password. 

• Specification of a password where none is required is always ignored. 

The following protection considerations and precautions should be observed 
when using commands which cause a data set access: 

• To access a VSAM data set using its cluster name, instead of data or index 
names, you must specify the proper level password for the cluster. The 
proper level password for the cluster is required even if the data or index 
passwords are nuU. 



Data Security and Protection 55 



Operator Prompting Code 



Attempts to Supply a Password 



• To access a VSAM data set using its data or index name, instead of its 
cluster name, you must specify the proper data or index password. 
However, if cluster passwords are defined, the master password of the 
cluster may be specified instead of the proper data or index password. 

• If a cluster has only null (not specified) passwords, you can access the data 
set using the cluster name without specifying passwords. This is true even if 
the data and index entries of the cluster have passwords defined. This 
allows unrestricted access to the VSAM data set as a whole but protects 
against unauthorized modification of the data or index as separate 
components. 



Computer operators and TSO-terminal users may be given the opportunity to 
supply a correct password if a processing program does not give the correct 
one when it tries to open a password-protected data set. When the data set is 
defined, you may specify a code to be used in lieu of the data-set name to 
prompt the operator or terminal user for a password. The prompting code 
keeps your data secure by not allowing the operator or terminal user to know 
both the name of the data set and its password. 

A data set's code is used for prompting for any operation against a 
password-protected data set. The catalog code is used for prompting when the 
catalog is opened as a data set, when an attempt is made to locate catalog 
entries that describe the catalog, and when an entry is to be defined in the 
catalog. 

If you don't specify a prompting code, VSAM identifies the job for which a 
password is needed with the JOBNAME and DSNAME for background jobs 
or with the DSNAME alone for foreground (TSO) jobs. 



When you define a data set, you can specify the number of times the 
computer operator or terminal user is allowed to try to give the correct 
password when a processing program is trying to open a data set. If the 
aUowed number of attempts is exceeded and you are using the System 
Management FacOities, a record is written to the SMF data set to indicate a 
security violation. 

Note: Using the TSO logon password counts as one attempt. 



Passwords for Non VSAM Data Sets 



When you define a non VSAM data set in a VSAM catalog, the data set is not 
protected with passwords in its catalog entry. You can password-protect a 
non VSAM data set when you create it, by specifying 

LABEL= (PASSWORD | NOPWREAD) in the DD statement that describes 
the data set (for more details, see OS/VS2 JCL). You use the PROTECT 
macro instruction to assign a password to the non VSAM data set (for more 
details, see 0S/VS2 Data Management Services Guide and OS/VS2 System 
Programming Library: Data Management). 

If the catalog is update protected, you must supply the catalog's update- (or 
higher-level) password in order to define, delete or alter a non VSAM data set. 
The password can be supplied as a subparameter of the command's 
CATALOG parameter, or as a response to the password-prompting message. 
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User-Security- Verification Routine 



In addition to password protection, VSAM allows you to protect data by 
specifying a program to verify a user's authorization. Specific requirements of 
the user-security-verification routine are described in the chapter 
"User- Written Exit Routines" in OS/VS Virtual Storage Access Method 
(VSAM) Programmer's Guide. To use this routine, simply specify the name 
of the authorization routine you have written in the AUTHORIZATION 
parameter of the DEFINE or ALTER command. 

If a password exists for the type of operation being performed, the password 
must be given, either in the command or in response to prompting. The 
user-security-verification routine is called only after the password specified is 
verified. The user-security-verification routine is bypassed whenever a correct 
master password is specified, whether or not the master password is required 
for the requested operation. 



Resource Access Control Facility (RACF) Protection 



Protecting User's Data 



Resource Access Control Facility (RACF) provides an optional software 
access control measure you can use in addition to or instead of passwords. 
Password protection and RACF protection can coexist for the same data set. 
When RACF protection is applied to a data set which is already password 
protected, password protection is bypassed and access is controlled solely 
through the RACF authorization mechanism. If a User-Security- Verification 
Routine (USVR) exists, it will not be invoked for RACF-defined data sets. 

Although passwords are ignored for a RACF indicated data set, they can still 
provide protection if the data set is moved to another system which does not 
have RACF protection. 

RACF authorization checking is generally compatible with the password 
authorization checking scheme. The compatibility includes the time at which 
the authorization check is made, the sources of authorization, and the level of 
authorization required. The RACF authorization levels of alter, control, 
update, and read correspond to the password levels of master, control, 
update, and read in VSAM. As an example, consider the authorization 
required to delete a VSAM data set. With passwords, this requires master 
level authorization either to the data set or to the containing catalog. (The 
catalog is a second source of authorization in this case.) If both the data set 
and catalog were RACF protected, it would take alter level authorization to 
delete the data set. 

Refer to OS/VS2 MVS Resource Access Control Facility (RACF) General 
Information Manual for more information. 



Sometimes, due to system or hardware failure, your data may be destroyed or 
made inaccessible to you. You should recognize the possibility of this 
occurring and take actions that will allow you to recover your data if such a 
catastrophe happens. 
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Preformatting Control Areas 



Backing Up Data 



When you define a cluster, you can indicate that VSAM is to preformat each 
control area as records are loaded into the cluster (RECOVERY) or is not to 
preformat them, in the interest of performance (SPEED). Preformatting 
clears all previous information from the direct-access storage area and writes 
an end-of-fUe indicator: 

. For an entry-sequenced or relative record data set, in every control interval 
in the control area. 

• For a key-sequenced data set, in the first control interval in the control 
area following the preformatted control area. (The preformatted control 
area contains free control intervals.) 

As records are loaded into a preformatted control area, there is always a 
following end-of-file indicator that indicates how far loading has progressed. 
If an error occurs that prevents loading from continuing, you can readUy 
identify the last successfully loaded record and resume loading at that point. 

Without Preformatting, an end-of-file indicator is written only after the last 
record is loaded. If an error occurs that prevents loading from continuing, you 
might not be able to identify the last successfully-loaded record — you might 
have to reload the records from the beginning. 



Two Access Method Services commands enable you to create a backup copy 
of your data: 

• EXPORT copies a VSAM cluster or alternate index and its catalog entries. 
The copy can be imported to another OS/VSl, OS/VS2, or DOS/VS 
system that includes VSAM or can be used as a backup. 

. REPRO copies a VSAM cluster or alternate index (without its catalog 
entry), a VSAM catalog, or a sequential data set. The copy can be used as 
a backup. 

The choice of using EXPORT or REPRO as a backup depends on a number 
of factors: 

• A backup copy created by EXPORT can only be a sequential data set. A 
backup copy created by REPRO can be a VSAM data set or a sequential 
data set. Also, the backup copy obtained by using REPRO can be a 
different type of VSAM data set than the original. You could, for example, 
back up a VSAM key-sequenced data set by copying it to a VSAM 
entry-sequenced data set using REPRO. By using the REUSE attribute 
when using REPRO to back up a VSAM data set, you have the facility of 
taking repeated backups to the same VSAM reusable target data set. 

• A backup copy created by EXPORT contains all the information necessary 
to redefine the VSAM cluster or alternate index when you IMPORT the 
copy. A backup copy created by REPRO does not contain this catalog 
information. If it is necessary to use the backup copy, you must delete the 
original data set, if it still exists, using the DELETE command. You must 
then redefine the data set using the DEFINE command prior to restoring it 
with the backup copy using the REPRO command. (Note that the delete 
and define operations would not be necessary if the original data set still 
exists and was defined with the REUSE attribute.) 
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Using EXPORT and IMPORT to transport or back up a key-sequenced data 
set or using REPRO to copy it reorganizes the data set — it rearranges data 
records physically in ascending key sequence (control-interval and 
control-area splits might have got them physically out of order) and balances 
free space quantities. 

After you have replaced a damaged data set with its backup copy, you can 
bring the backup copy up to date with the original by rerunning the jobs that 
updated the original between the time it was backed up and the time it 
became inaccessible. 

Backing up the data sets in a user catalog enables you to recover from damage 
to the catalog. You can import the backup copy of a data set whose entry was 
lost or redefine the entry and reload the backup copy. If the catalog was 
completely lost, you could redefine it, then import or redefine and reload all 
of the data sets that were defined in the catalog. (Backing up the catalog itself 
is discussed in the section "Protecting VSAM Catalogs.") 

Exporting and Importing a Data Set 

You can use the EXPORT command (with the TEMPORARY parameter) to 
copy a VSAM cluster and its catalog entries onto a movable volume (that is, a 
demountable direct- access volume or a magnetic-tape volume). You can then 
use the IMPORT command either to move the portable copy to another VSl, 
VS2, or DOS/VS system that includes VSAM or to replace the original 
cluster and its catalog entries. The portable copy itself is inaccessible for 
processing. 



Making a Copy of a Data Set 



You can use the REPRO command to copy a VSAM or sequential data set 
into another VSAM or sequential data set, newly defined (for protection) in 
another catalog. (The REPRO command does not copy the data set's catalog 
information.) You can use the REPRO command with the REPLACE 
parameter to merge the backup copy into the original data set, or you can 
delete and redefine the original data set and use REPRO to reload the backup 
copy into it. Or, because the backup copy is itself accessible for processing, 
you can replace the original with it. (You have to make available for 
processing the catalog in which you defined the backup, and you have to use 
the name of the backup.) 

If you periodically process a data set sequentially, you can easily create a 
backup copy as a by-product of normal processing. You can use this backup 
copy like one made by way of REPRO. 



Ensuring Accessibility of Secondary Extents 



When a VSAM catalog is damaged so that you have to use a backup copy of 
the catalog (see "Protecting VSAM Catalogs," below, for information about 
backing-up catalogs), any extents that were allocated to the catalog's data 
sets since the backup copy was made become inaccessible. 

In an entry-sequenced or a relative-record data set, the records in the new 
extents will have been added at the end. But in a key-sequenced data set, 
some of the records in the new extents could have been moved there becaiise 
of a control-area split. 



\ 
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Corrective Measures 



To ensure that all of the records in a catalog's data set are accessible after you 
fall back to a backup copy of the catalog, you can: 

• Eliminate the need for secondary extents in the data set by providing a 
sufficiently large primary space allocation. 

• Reduce the number of secondary extents by providing for sufficiently large 
secondary space allocations. Whenever a secondary extent is aUocated, you 
can make a new backup copy of the catalog. You can monitor the growth 
of a data set by way of the LISTCAT command or the SHOWCB macro. 
(The use of SHOWCB to display statistics is described in OS/VS Virtual 
Storage Access Method (VSAM) Programmer's Guide.) 

For growth that did not require secondary allocation in a data set since the 
backup copy of its catalog was made, you can use the VERIFY command to 
reset the end-of-file indicators in the catalog after you fall back to the backup 
copy. 



When you discover that a catastrophe destroyed part or all of your on-line 
data, you can replace the destroyed data set with its backup copy (if one 
exists): 

o You can use the REPRO command with the REPLACE option to merge 
the backup copy with the destroyed data. When only part of your data set 
is damaged, you can specify REPRO parameters that allow you to replace 
only the records in the damaged part of the data set. 

• You can use the IMPORT command to totally replace a VSAM cluster 
whose backup copy was built using the EXPORT command. The IMPORT 
command uses the backup copy to replace the cluster's contents and 
catalog information. 



Protecting VSAM Catalogs 



Because you cannot gain access to a VSAM data set without the master or 
user catalog in which the data set is defined, you need to make sure that your 
catalogs can always be made available. You can take preventive measures to 
minimize the possibility of catalog loss and corrective measures to recover 
11 om loss, should it occur. 

The effect of the loss of a catalog can be minimized by the following: 

• Widespread use of user catalogs — a user catalog for each volume, where 
possible. (It is not possible for multivolume data sets — one catalog must 
control all the volumes of a data set.) Compare the effect of the loss of a 
catalog when (a) 10 data sets are cataloged in each of 10 catalogs and (b) 
50 data sets are cataloged in each of 2 catalogs. The fewer the catalogs the 
greater the disruption in the event of loss of a catalog. 

• Limited use of the master catalog. 

• Dedicated use of volumes for VSAM data sets to segregate VSAM and 
nonVSAM recovery. You can dedicate a volume by defining a VSAM data 
space that occupies the whole volume. If some of the space on a volume 
does not belong to a VSAM data space, OS/VS may allocate that space to 
a nonVSAM data set. If you follow a dump/restore recovery procedure 
(outUned later) you will have to fall back to a previous copy not only of the 
VSAM data and catalog, but also of the nonVSAM data. 
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Using REPRO to Back Up a Catalog 



You can use the REPRO command to unload (make a backup copy of) a 
catalog. If the catalog becomes inaccessible, you can use REPRO to reload 
the copy. The section "Backing up a Catalog" in the chapter "Copying and 
Printing" describes catalog unload/reload. 

The backup copy might not reflect current information for some of the 
cataloged objects. The section "Updating a Backup Catalog" below describes 
how to make a backup catalog current. 



Backing up the Master Catalog 



An OS/VS2 system requires a master catalog — ^if a system or hardware 
failure damages the master catalog, the system cannot be used until the 
damage is corrected, unless you have a backup master catalog. Without a 
copy of the master catalog, you might have to generate a new system (using 
SYSGEN processing). 

Because the system requires a master catalog, the reload procedure described 
in "Backing up a Catalog" in the chapter "Copying and Printing" requires 
modification for reloading the master catalog. Reloading the master catalog 
with REPRO works fine, if you have a master catalog to reload. When only 
some of the entries in the master catalog have become inaccessible, and the 
master catalog itself is still operational, you might be able to reload the 
backup catalog into it. Otherwise, you can get a master catalog by: 

• Using lEHDASDR (on another system) to restore the volume that contains 
the master catalog (from a tape onto which you have previously dumped 
the volume). You can do an IPL (initial program load) to bring your 
system up with the restored volume and then use REPRO to reload the 
backup into the restored version of the catalog. (If the backup is no more 
recent than the restored catalog, you can use the restored version without 
reloading.) 

With DUMP/RESTORE, you should design the volume that contains the 
master catalog to contain information that changes very little. Thus, you 
won't lose changes when you restore the volume. And, to avoid needing 
another system to restore the volume from a tape, you could have two 
direct-access volumes (with the same volume serial number) that contain a 
copy of the master catalog. 

• Using DEFINE (on another VS2 system) to define a user catalog with the 
same name as your master catalog. You then use REPRO (still on the other 
system) to reload the user catalog with the backup copy of the master 
catalog. You can bring up your system with the reloaded user catalog as 
your master catalog. 

Dumping a Catalog and Its Data Sets 

This procedure calls for periodically dumping the volume(s) upon which a 
catalog and its data sets are stored with the lEHDASDR utility program (or 
with some other utility that achieves the same effect). Then, if the ciatalog is 
lost or somehow becomes inaccessible, you would be able to restore the 
volumes (or alternate volumes with the same volume serial numbers). The 
volumes would then contain what they contained when the backup copies 
were made. See "Updating a Backup Catalog" below about how to bring the 

iw restored catalog up to date. 

1 

/ 
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When you use lEHDASDR to dump a volume containing a VSAM catalog, 
you should ensure that all update activity (for example, DEFINE, DELETE, 
ALTER, data set extension, etc.) is quiesced. If any catalog update activity 
occurs during the dump operation, it is possible for the chain of free records 
in the catalog's low key range to be damaged in the backup copy. Then, if it is 
necessary to restore the backup copy, the damaged chain will be introduced 
into the restored copy. 

If some of the space on a volume does not belong to a VSAM data space, the 
system may have allocated that space to nonVSAM data sets. With 
DUMP/RESTORE, you will have to fall back to a previous copy not only of 
the VSAM data sets and catalog, but also of the nonVSAM data sets. 

When you use lEHDASDR to dump or restore a volume that contains VSAM 
objects (that is, clusters, catalogs, data spaces, and alternate indexes), you 
must include a JOBCAT or STEPCAT DD statement with the lEHDASDR 
job or jobstep to describe the VSAM catalog that owns the volume. The 
volume's table of contents (VTOC) indicates that part of the volume's 
contents is password-protected, and that the volume is owned by a VSAM 
catalog (that is, the passwords for the password-protected objects are part of 
the object's catalog information). However, the volume's VTOC does not 
identify the catalog that contains the passwords. Before a volume is dumped, 
the system asks the operator for the correct password of each 
password-protected object on the volume. However, if the volume is 
RACF-protected, RACF read authorization to the volume overrides VSAM 
password protection. For more information on how to use lEHDASDR to 
dump and restore volumes containing VSAM objects, see 0S/VS2 MVS 
Utilities. 



Updating a Backup Catalog 



A reloaded or restored backup catalog won't reflect any changes in the 
original catalog between the time you unloaded it to make the backup and the 
time it became inaccessible. Three types of changes may have occurred: 

• Entries may have been deleted by way of DELETE or permanently 
exported by way of EXPORT PERMANENT. You can remove these 
entries from the backup catalog with DELETE NOSCRATCH, which is 
described below under "VSAM Catalog Cleanup." 

• Entries may have been defined by way of DEFINE, imported by way of 
IMPORT, or defined (nonVSAM entries only) by the VS2 Scheduler. You 
can use DEFINE NONVSAM to bring the backup catalog up to date on 
nonVSAM entries. But a VSAM object defined by an entry missing from 
the backup catalog is no longer accessible. To regain the use of the space 
on a volume or in a VSAM data space whose entry is missing from the 
backup catalog, you can use ALTER REMOVEVOLUMES (described 
below under "VSAM Volume Cleanup"). 

To recover objects that are lost in this way, you will have to redefine them 
and rerun the jobs that loaded and updated them, or you will have to have 
backed them up as described above under "Backing Up Data." 

• Entries may have been updated to describe extensions. For an extension 
that used space already allocated to an object (that is, before the original 
catalog was unloaded to make the backup), you can use the VERIFY 
command to update the object's end-of-file indicator. But for an extension 
that used newly-allocated space, you cannot update the backup catalog to 
recover the data in the extension. (See "Ensuring Accessibility of 
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VSAM Volume Cleanup 






Secondary Extents" above about how to protect yourself from this loss of 
data.) 



You normally take away the ownership of a volume from a VSAM user 
catalog by deleting all the objects and all the data spaces on the volume. But 
if a user catalog is inaccessible for some reason, or it no longer contains 
entries for the volume or its data spaces (as, for example, when you reload a 
backup catalog), you cannot use the DELETE command to take away 
ownership. 

The ALTER command with the REMOVEVOLUMES parameter enables 
you to get rid of all the VSAM data spaces on a volume without gaining 
access to the catalog that owns the volume. ALTER REMOVEVOLUMES 
overwrites the data spaces with binary zeros and rewrites the VTOC to 
remove the data spaces' format- 1 DSCBs and to turn off the VSAM 
ownership bit in the format-4 DSCB. 

When the user catalog itself is on the volume, ALTER REMOVEVOLUMES 
overwrites it as well. Thus, you can use ALTER REMOVEVOLUMES to 
clean up a volume that contains a user catalog that has become inaccessible. 
You should first use EXPORT DISCONNECT to remove the catalog's^ entry 
in the master catalog prior to using ALTER REMOVEVOLUMES. 

ALTER REMOVEVOLUMES does not remove nonVSAM data sets from a 
volume, nor does it remove VSAM objects from a volume owned by the 
master catalog. See the section "VSAM Volume Recovery Function" for 
detaUs on how to specify the ALTER REMOVEVOLUMES function. 

Note: 

• ALTER REMOVEVOLUMES is also used simply to take away from a 
catalog ownership of a candidate volume that does not yet contain a 
VSAM data space and is not referenced by any VSAM objects. 

. You should not use ALTER REMOVEVOLUMES to get rid of VSAM 
objects on a volume owned by a catalog that you can still use — ^you should 
use the DELETE command. 

• If you are using the ALTER REMOVEVOLUMES function for a volume 
containing a user catalog, you should make sure that the user catalog is not 
open. You can do this by including a DD statement (which is not a 
JOBCAT or STEPCAT DD statement) which identifies the user catalog 
and specifies DISP=OLD in the job step that includes the ALTER 
REMOVEVOLUMES command. The user catalog should not be identified 
in a JOBCAT DD statement in the ALTER REMOVEVOLUMES job, 
nor in a STEPCAT DD statement in the ALTER REMOVEVOLUMES 
job step, nor in any other DD statement(s) or Access Method Services 
command parameter(s) that would cause the catalog to be allocated and 
opened as a catalog prior to the time the ALTER REMOVEVOLUMES 
command is executed (for example, use of a data-set name with a 
high-level quaUfier which is the alias of the user catalog). 

If the user catalog that owns the volume is available, you can use the 
DELETE SPACE command with the FORCE option to get rid of all VSAM 
data spaces on a volume whether or not they contain VSAM data sets. 
DELETE SPACE FORCE deletes all VSAM data spaces, marks any VSAM 
data sets contained therein as unusable in the catalog, and releases ownership 
of the volume. If your volume contains VSAM data space(s) you wish to 
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eliminate but some VSAM data sets you wish to save, you can use the 
EXPORT command to export the data sets you wish to save. Then use 
DELETE SPACE FORCE to eliminate all VSAM data spaces on the volume. 
After redefining the data spaces, you can reestablish your data sets by using 
the IMPORT command. 

DELETE SPACE FORCE cannot be used for a volume that contains a user 
catalog. DELETE USERCATALOG FORCE can be used to DELETE a user 
catalog without first deleting all its entries. All data spaces are deleted from 
each volume owned by the catalog, including the catalog volume itself, and 
volume ownership is released by VSAM. 



Changing a Volume's Serial Number 



When you change the volume serial number of a volume that contains VSAM 
objects, the VSAM objects can no longer be located when the objects' catalog 
volume information is referenced (you can use the LABEL statement of the 
lEHDASDR program to change a volume's serial number, or "clip" the 
volume). You should use the following procedure to change the volume's 
serial number, to allow the VSAM objects on the volume to be located: 

1. Issue the EXPORT PERMANENT command for each VSAM object (that 
is, for each alternate index and cluster) on the volume. When the volume 
also contains a VSAM catalog, issue an EXPORT DISCONNECT 
command to disconnect the user catalog from the master catalog. The 
EXPORT command copies each VSAM object and its catalog entry onto a 
movable volume. The object's entry in the user catalog is deleted. 

2. Issue the DELETE command to delete all empty data spaces on the 
volume, and to delete the volume entry from the catalog. NonVSAM data 
sets are described in the volume's VTOC and are not affected by the 
DELETE command. 

3. When the volume contains an empty catalog (that is, the catalog only 
describes space on the volume), delete the catalog. If the empty catalog 
describes space on more than its own volume, you can delete the space on 
each volume first, then delete the catalog. 

4. Execute the lEHDASDR program with the LABEL statement to change 
the volume's serial number. 

5. If the catalog was deleted in step 3, it must be redefined when beginning 
this step. Issue the DEFINE SPACE command to build a data space on the 
volume, to establish the VSAM catalog's ownership of the volume, and to 
build a volume entry that points to the volume with its new serial number. 
The data space you define should be large enough to contain all of the 
subaUocated VSAM objects you removed from the volume during step 1. 
(When you execute the lEHDASDR program, you might reorganize the 
nonVSAM data sets remaining on the volume, so that the space available 
for the VSAM data space is contiguous.) 

6. Issue the IMPORT command for each VSAM object that was removed 
from the volume during step 1 , specifying the new volume information for 
the object. 



64 0S/VS2 Access Method Services 



VSAM Catalog Cleanup 



When a volume becomes inaccessible, you can use the DELETE command 
with the NOSCRATCH parameter to remove from the catalog that owns the 
volume the entries for the VSAM objects on the volume. You can also use 
DELETE NOSCRATCH to remove from a backup catalog entries for the 
VSAM objects that were deleted from the original catalog after the time it 
was unloaded to make the backup. DELETE NOSCRATCH removes an 
entry without gaining access to the volume indicated in the entry. You should 
keep in mind that, if the cluster, alternate index, or pagespace was defined 
with the UNIQUE attribute, a format- 1 DSCB was written on the object's 
volume. If you specify NOSCRATCH and the format- 1 DSCB still exists, it 
will not be erased from the VTOC. (DELETE without NOSCRATCH 
specified allows Access Method Services to gain access to a volume to change 
the VTOC or overwrite an object with binary zeros.) 

VSAM cleans up the catalog*. 

. When DELETE CLUSTER, DELETE ALTERNATEINDEX, or 
DELETE PAGESPACE is specified, by deleting the cluster, alternate 
index, or pagespace entry. (Note: NOSCRATCH cannot be specifed for 
these entry types if they are defined in a recoverable catalog.) 

• When DELETE SPACE is specified, by deleting the volume entry. The 
volunle entry must be empty (that is, you must first delete the entries of all 
VSAM objects that are indicated in the entry). 

Exporting a Catalog's Data SeU 

While the primary purpose of the EXPORT command is to allow you to move 
data sets and user catalogs between systems, it can also be used to create 
backup copies of particularly sensitive data sets. The EXPORT command 
copies a data set and extracts the data set's definition from the catalog in 
which it is defined. If you use Access Method Services to periodically export a 
data set, you can redefine the catalog should it be lost, define a VSAM data 
space if the data set is to be suballocated, and import the data set into the 
new catalog. With export/import you can control the level of each data set 
individually. If you exported a data set for backup after each run, you 
wouldn't have to rerun any jobs to bring the backup copy up to date. 

A single volume per user catalog is desirable when your system contains a 
large number of single-volume data sets. 

Moving a Catalog to Another System 

You can move a user catalog from your OS/VS2 MVS system to another 
system (that is, to an OS/VS or DOS/VS system that includes VSAM) to 
make the objects cataloged in the user catalog available to programs running 
on the other system. The user catalog might own only the volume on which it 
resides. In this case, the volume, its catalog, and its contents (that is, VSAM 
clusters, nonVSAM data sets, and free space) can be moved as a single unit to 
another system. When the catalog owns more than one volume, each volume 
owned by the catalog must either be moved to the other system with the 
catalog or be deleted before the catalog is moved. 

Caution: When you move a recoverable catalog to a system that does not 
support recoverable catalogs, the recoverability of the catalog is destroyed 
when any of the catalog's records are modified, deleted, or added. 
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Catalog Recovery 



You use the EXPORT command with the DISCONNECT option to remove a 
user catalog from its OS/VS system. The EXPORT command deletes the user 
catalog's connector entry in the system's master catalog. The EXPORT 
command also deletes all alias entries that point to the user catalog's 
connector entry. The catalog, its cataloged objects, and its volume(s) are now 
unavailable to users of the old system. 

When the user catalog has aliases, you should take care to hst the ahases 
before you issue the EXPORT command. You can use the LISTCAT 
command to list the catalog's aliases, which are in the master catalog. You can 
use the list of aliases to help you reconstruct the alias entries in the new 
system's master catalog. 

You use the IMPORT command with the CONNECT option to make the 
exported catalog available to the new OS/VS system. The IMPORT 
command builds in the new system's master catalog a user-catalog connector 
entry that points to the user catalog's volume. You should issue a DEFINE 
ALIAS command to build an ahas entry in the new system's master catalog 
for each of the user catalog's aliases. 



All VSAM catalogs can be defined with the RECOVERABLE attribute that 
makes it possible to recover VSAM data sets and their catalog entries should 
the catalog be damaged or destroyed. Recovery is achieved by recording a 
copy of all catalog information about a given volume and its data sets on that 
volume as well as in the catalog itself. Recovery information is recorded on 
each volume owned by a catalog. Space for this information is automatically 
set aside when you acquire VSAM ownership of a volume and also when you 
define the catalog itself. There is no separate catalog entry for the recovery 
space: VSAM records its physical track address in the volume's format-4 
DSCB. 

The recovery information in the volume's catalog recovery area (CRA) is 
updated immediately whenever parallel information in the catalog is changed. 
The affected volume(s) must be mounted, and the kind of operation to be 
performed on an object (data space, cluster, path, etc.) determines which 
volume(s) to mount. 

To recover a VSAM data set and its catalog entries, you issue the 
EXFORTRA command. EXPORTRA uses the information in the CRA 
rather than the catalog to gain access to VSAM data sets and produce a copy 
of the VSAM data sets. The copy can be introduced back into the system by 
means of the IMPORTRA command. 

RESETCAT is another catalog-recovery tool. If, for any reason, 
inconsistencies develop between your catalog and the CRAs of its owned 
volumes, you should consider RESETCAT as your recovery vehicle. 
RESETCAT is basically a synchronization process between a catalog and its 
associated CRA(s). If your catalog or any of its owned volumes becomes 
unusable, you can restore a backup volume. However, this will not solve your 
problems because inconsistencies wiU undoubtedly exist between your catalog 
and the CRAs of the volumes it owns. Either the catalog or the CRAs will be 
downlevel (entries will not precisely describe the data sets). RESETCAT 
provides the necessary synchronization facility to ensure consistency between 
the catalog and its volumes. RESETCAT confines its processing to the 
catalog and CRAs; VSAM data sets are unaffected by this operation; no data 
movement takes place. 
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Regaining Access to Data 
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You can use the LISTCRA command either to list the contents of the CRA 
before you do selective recovery or to list the entries in the recovery area that 
are different from those in its associated catalog. 

See the "Restoring Catalog Entries After System Failure" chapter for more 
information and examples on catalog recovery. 

If you are presently using an OS/VS2 system without recoverable catalogs, 
see Appendix H for information on making your master catalog recoverable. 



Using some of the corrective measures listed, you can analyze and recover 
from the following conditions: 

• Inaccessible data set 

• Unusable catalog 

• Inaccessible volume 

You can use the LISTCRA command with the COMPARE option to identify 
mismatches between the catalog recovery area (CRA) and the catalog itself. 
The records in the CRA are used as a base for comparison and, whenever a 
mismatch is detected, LISTCRA prints the CRA record and its matching 
catalog record and identifies the mismatch by printing asterisks below the 
mismatched area(s) of the records. (The LISTCRA command, as well as 
EXPORTRA, IMPORTRA, and RESETCAT, is usable only with recoverable 
catalogs.) The mismatches detected by LISTCRA vary in their degree of 
seriousness. The type of mismatch determines the level of recovery that is 
required. The following list (ordered by severity) shows the type of mismatch, 
why it may have occurred, and how serious it is. The "Type" column indicates 
the section of the catalog record or group of fields in which the mismatch 
occurred. If the LISTCRA command detects more than one area of mismatch, 
only the most serious mismatch is identified. Subsequent sections of this 
chapter teU how to use corrective measures to recover. 

Figure 28 in Appendix D shows an example of the LISTCRA output using the 
DUMP COMPARE options. 
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Catalog Vohune Records 



♦MISCOMPARES 
Message 

DATA SPACE 
EXTENTS 



Type 

Mismatched data 
space group 



Cause 

A difference in the 
number, size, and/or 
location of VSAM data 
spaces. 

A difference in the 
number and/or location 
of extents for one or 
more data sets. 

Space has been 
extended or deleted. 



Severity 

Requires 
recovery of the 
entire volume. 



Requires 
recovery of the 
entire volume. 



Requires 
recovery of the 
entire volume. 



DATA SET 
DIRECTORY 



Mismatched data set 
directory 



A difference in the 
names and/or number 
of data sets associated 
with this volume. 



Requires 
recovery of the 
entire volume. 



VSAM Object Records 



♦MISCOMPARES 
Message 

CATALOG ENTRY 
HAS DFFFERENT 

NAME 



Type 

Mismatched 
entryname 



VOLUME OR 
KEYRANGE 



Mismatched volume 
or key range in the 
volume information 
set of fields. 



EXTENTS 



Mismatched extents 
in the volume 
information set of 
fields. 



Cause 

The catalog was 
restored, or the volume 
containing the data set 
was restored. As a result 
the record in the catalog 
pointed to by the CRA 
record is no longer for 
the same object. 

The catalog was 
restored, or the volume 
contining the data set 
was restored. As a result 
the object's volume 
locations or keyranges 
in the CRA do not 
match those in the 
catalog. 

Data set was not 
properly closed, the 
catalog was restored, or 
the volume containing 
the data set was 
restored. 



Severity 

Requires data 
set recovery. 



Requires data 
set recovery. 



Requires data 
set recovery. 
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VSAM Object Records (Continued) 
Type 



♦MISCOMPARES 

Message 



HIGH USED RBA 



STATISTICS 



Mismatched high 
used Relative Byte 
Address 



Mismatched 
statistics in the 
Access Method Data 
Set Statistics Block 
(AMDSB). 



Cause 

Same as for mismatched 
extents. 



Same as for mismatched 
extents. 



Severity 

Requires use 
of the VERIFY 
command to 
correct the 
high RBA. 

No recovery 
action is 
required; 
mismatched 
statistics do 
not affect the 
accessibility of 
data. 



OTHER 



Same as for mismatched Depends on 
extents. the type of 

mismatch. 



Mismatch of 
something other 
than the above 
fields, e.g. 
passwords. 

In general, there are two types of data recovery in terms of the currency of 
the recovered data; repair and reset. 

The repair type of data recovery operation restores addressability and access 
to the most current version of the data. Repair operations are generally used 
to correct problems such as read and write errors associated with the data 
itself or with the data description, for example, by assigning alternate tracks. 

The reset type of data recovery operation restores addressability and access 
to a version of the data other than the most recent. Reset operations are 
generally used to correct logical problems such as a programming error or 
faulty transactions. Reset is generally the most common form of recovery, 
probably because of the types of problems encountered and the level of data 
available for recovery. An example of a reset operation is the dump (copy) 
and restore of a volume. 

The following list of utility programs, whether Access Method Services, 
VSAM, or system, shows the type(s) of data recovery (or analysis) each 
program can undertake: 



EXPORT/IMPORT 
REPRO 

EXPORTRA/IMPORTRA 
COPY and RESTORE 
LISTCRA (COMPARE) 
DELETE UCAT(FORCE) 
ALTER REMOVEVOLUMES 
DELETE SPACE(FORCE) 

NOSCRATCH 
DELETE CLUSTER 

NOSCRATCH 
VTOC UTILITY(SUPERZAP) 
DELETE SPACE (FORCE) 
VERIFY 
RESETCAT 



Reset 

Reset/repair 

Repair (recoverable catalogs only) 

Reset 

Analysis (recoverable catalogs only) 

Reset/repair 

Reset/repair 

Reset/repair 

Reset/repair 

Reset/repair 

Reset/repair 

Repair 

Reset/ repair (recoverable 

catalogs only) 



REPRO can be used to create a backup copy of the catalog. The catalog can 
be reloaded (using REPRO) from this backup copy to minimize the amount 
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of work required to accomplish recovery. The usefulness of a backup copy 
depends on what modifications have been made to the catalog since the 
backup was created, subsequent to taking a backup copy will affect the 
usefulness of the backup catalog: 

Altering the amount of space controlled by the catalog. The volume entry in 
the backup catalog is no longer valid and will mismatch with the catalog 
recovery area. 

DeHnuig, altering, or deleting data sets. The volume entry and some of the 
data set entries in the backup copy are no longer valid. 

Suballocating space to a VSAM data set. The volume space map is 
invalidated which, in itself, is not serious. However, the data set entry is 
also invalidated, a serious problem. (See "Ensuring Accessibihty of 
Secondary Extents" for more information.) 

Several of the recovery procedures use volume restore. If this is indicated, one 
or the other of the following must be true: 

• The volume being restored does not contain multivolume data sets. 

• If a volume does contain a portion of a multivolume data set, aU volumes 
which contain portions of those multivolume data sets are treated as a 
single unit; that is, if a volume restore is required, the entire set is restored. 
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CREATING AND CATALOGING OBJECTS 



VSAM uses catalogs as a central information point for all VSAM data sets 
and the direct-access volumes on which they are stored. You can define a 
VSAM object in a VSAM catalog only by using the Access Method Services 
DEFINE command. Additionally, you can use the DEFINE command to 
define nonVSAM objects in a VSAM catalog. 

When you issue the DEFINE command to catalog an object. Access Method 
Services builds a catalog entry to describe the object. The VSAM objects you 
can define are: 

• User catalog, which is a collection of information about nonVSAM objects, 
and about VSAM objects that reside on the volumes owiied by the user 
catalog. You can create a user catalog at any time. A pointer to the user 
catalog is put in the system's master catalog. A master catalog is created 
during the SYSGEN process. The VSAM master catalog is the OS/VS2 
system's primary catalog. 

• Data space, which is direct-access device space used for a catalog, for 
VSAM clusters, for page spaces, and for alternate indexes. VSAM controls 
the allocation of space within each data space. 

• Cluster, or VSAM data set, which is a collection of user-data records. 
There are three types of cluster data organization: 

- Entry-sequenced, or sequential, in which data records are read or 
written sequentially from one end to the other (first to last for writing, 
either dkection for reading). 

- Key-sequenced, or indexed, in which a data record is read or written 
based on its key value. A key is a field, shorter than and within the 
record, that identifies the record. 

- Relative-record, or direct, in which a data record is read or written 
based on its relative-record number — its displacement, in records, from 
the beginning of the cluster. 

• Alternate index, which allows you to read and write data records in an 
entry-sequenced or key-sequenced cluster (called the base cluster) based 
on an alternate key. 

• Path, which is a data-set name for the combination of an alternate index 
and its base cluster, or an alias for a VSAM cluster. A path entry can be 
password protected. 

• Page space, which is an amount of direct-access device space to be used 
exclusively by the OS/VS2 system. 

The nonVSAM objects you can define are: 

• NonVSAM data set, which is a collection of data records with sequential, 
partitioned, direct, or indexed-sequential data organization (that is, not 
VSAM data organization). 

• Generation data group, which is a collection of nonVSAM data sets that 
are grouped together in a time-dependent manner. 

• Alias, which is an alternate name for a user catalog or nonVSAM data set. 
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Before an object can be defined, you must have a VSAM catalog in which to 
define the object. Every VS2 system must have a VSAM master catalog 
before initial program load (IPL) is done for the system. 

When you define an object, you specify attributes to be associated with it. 
The attributes include, for example, any passwords required to use data and 
how space is to be allocated. After the object is defined, it can be processed 
with other Access Method Services commands and with the user's VSAM 
program. After a cluster is defined, for example, you can load data records 
into it by using the REPRO command. 

VSAM clusters, alternate indexes, page spaces, and catalogs are stored in data 
spaces. You can allow a data space to contain many VSAM objects by simply 
not specifying otherwise (the usual case and the default), or you can restrict a 
data space so that it contains only one VSAM object. In the usual case, you 
define a data space first, then define the data sets. To define a VSAM object 
as the only one in its data space, specify the parameter UNIQUE when you 
define the data set. When the object is defined, VSAM allocates a unique data 
space and assigns it to the object. 

Refer to the chapter: "Command Format" for a description of the command 
format for DEFINE USERCATALOG. Examples of defining user catalogs 
are also included. 



Preventing Duplicate Names in Catalogs 



With multiple catalogs (the master catalog, user catalogs, and OS/VS 
CVOLs), you should take care so that a data-set name in one catalog is not 
duplicated in another catalog. It is possible to have the same data-set name in 
more than one catalog. 

Access Method Services prevents you from cataloging two objects with the 
same name in the same catalog, and from altering the name of an object so 
that its new name duplicates the name of another object in the same catalog. 
However, this does not prevent duplication of names from one catalog to 
another. A following section, "Order of Catalog Use: DEFINE," describes 
the order in which one of the catalogs available to the system is selected to 
contain the to-be-defined catalog entry. When you define an object, you 
should ensure that the catalog the system selects is the catalog you want the 
object's entry in. 

Additionally, duplication is not prevented when a user catalog is imported into 
a system; no check is made to determine whether the imported catalog 
contains a name that another catalog already in the system contains. 



JCL and Dynamic Allocation (DEFINE) 



Defining an object does not normally require that a volume be mounted, 
because the availability of space in data spaces can be determined by 
examining the volume information in the catalog. A volume must be mounted 
whenever its VTOC has to be consulted or modified, that is, when a data 
space, a unique data set, or a catalog is being defined. If the catalog in which 
the object is being defined is recoverable, the volume containing the catalog 
recovery area to be updated must be mounted. (Refer to the section 
"Restoring Catalog Entries After System Failure" for a description of the 
catalog recovery volume.) Before a system component, such as VSAM or 
Access Method Services, can process a data set or volume, the OS/VS system 
allocates the data set or volume to the system component. Usually, the data 
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set or volume is allocated to the system component when the OS/VS 
Scheduler processes your job control language (JCL) DD statements. 

However, when a data-set name or volume-serial number is specified with an 
Access Method Services command, but its data set or volume has not been 
described with a DD statement, the data set or volume is allocated 
dynamically. The information describing a data set that the DD statement 
would have provided is extracted from the data set's entry in the catalog. This 
type of allocation is called dynamic allocation. The data-set's volume should 
be mounted as permanently resident or reserved to ensure successful dynamic 
allocation. 

If JCL is used to allocate a volume, include a DD statement of the form: 

//ddname DD 1;NIT=( type [ , mitcount ] [,DEFER] ), 
// VOLUME=SER=( serial [ , serial! , ...] ),DISP=OLD 

• UNIT= can specify a device type and volume-serial number for any 
direct-access storage device that is supported by your OS/VS system. 

• VOLUME=SER= indicates the serial number(s) of the volume(s) on 
which data spaces are to be allocated. When more than one volume is 
indicated, all volumes must be of the same device type. 

• DISP=OLD is required because VSAM allocates space to VSAM objects 
(that is, catalogs, clusters, alternate indexes, and page spaces). When you 
code DISP=NEW, the OS/VS system allocates space to the object. The 
space that the system allocates is not recorded in the object's catalog entry. 
Unless the object is a nonVSAM data set, the space allocated by the 
system is not available for the object's use. 

Order of Catalog Use: DEFINE 

The order in which catalogs are used when an entry is defined is: 

• If a catalog is specified in the CATALOG parameter, that catalog is 
selected to contain the to-be-defined entry. 

• When a nonVSAM generation data group (GDG) data set is defined, the 
catalog containing the GDG base is selected to contain the to-be-defined 
nonVSAM entry. Otherwise, 

• The first user catalog specified in the current job step (STEPCAT) or, if 
none is specified for the job step, the first user catalog in the current job 
(JOBCAT) is selected to contain the to-be-defined entry. (The section 
"JOBCAT and STEPCAT DD Statements" describes how you can specify 
a user catalog for the current job step or current job.) Otherwise, 

• If no user catalog is specified for the current job step or job, and the 
entry's name is a qualified name, and the first qualifier (that is, the first 
one to eight characters before the period) is the same as: 

- the name of a user catalog, or 

- the alias of a user catalog, 

the catalog so identified is selected to contain the to-be-defined entry. 

• If no catalog has been identified, either explicitly or implicitly, VSAM 
defines an object in the master catalog. 
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The DEFINE Command: How Parameters are Organized 



When you define a catalog, cluster, or alternate index, you can specify 
attributes in several different ways. The parameter set for DEFINE 
USERCATALOG, CLUSTER, and ALTERNATEINDEX is directly related 
to the way in which the attributes are stored in the VSAM catalog. The 
catalog entries which describe a VSAM catalog, cluster, or alternate index 
are: 

• The cluster entry, which describes attributes pertaining to the cluster or 
catalog as a whole; these are primarily protection attributes. 

. The alternate index entry, which describes attributes pertaining to the 
alternate index as a whole; these are primarily protection attributes, 

• The data entry, which describes attributes pertaining to the data 
component of a catalog, cluster, or alternate index. 

• The index entry, which describes attributes pertaining to the index 
component of a catalog, key-sequenced cluster, or alternate index. 

When you specify attributes as parameters of USERCATALOG, CLUSTER, 
or ALTERNATEINDEX, they are defined in the VSAM catalog in the 
cluster or alternate index entry if they pertain to that entry; for example, 
protection attributes. However, when you specify attributes as parameters of 
USERCATALOG, CLUSTER, or ALTERNATEINDEX which pertain to 
the data and/or index entries. Access Method Services directs the attributes 
to the proper entry. For example, if you specify the WRITECHECK attribute 
as a parameter of CLUSTER, it wiU not be defined in the CLUSTER entry 
but will be entered in the DATA entry and the INDEX entry in the catalog. 
When you specify attributes as parameters of DATA or INDEX, they are 
defined in the VSAM catalog directly in the data or index entry. You may use 
the LISTCAT command with the ALL option to Ust catalog entries and 
determine where the various attributes are stored in the catalog. "Appendix 
B: Interpreting LISTCAT Output Listings" describes the various attributes 
for each type of entry. 

Except for protection attributes, if you specify the same attribute as a 
subparameter of USERCATALOG, CLUSTER, or ALTERNATEINDEX 
and also as a subparameter of DATA and/or INDEX, the value of the 
attribute specified at the DATA/INDEX level overrides the value of the 
attribute specified at the USERCATALOG, CLUSTER, or 
ALTERNATEINDEX level. 

Since Access Method Services directs the attributes you specify to the proper 
entry, you do not need to specify any attributes as parameters of DATA or 
INDEX. However, you may wish to specify attributes as parameters of 
DATA and INDEX if you wish to: 

• Specify a name for the data and index components of a cluster or alternate 
index. 

• Specify unique protection attributes for the data and index components of 
a cluster or alternate index. 

• Specify space allocation for the data component only or for the data and 
index components separately of a catalog, key-sequenced cluster, or 
alternate index. 

• Specify volumes of a different device type for the data and index 
components of a key-sequenced cluster or alternate index. 
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• specify a different variation of the same attribute for the data and index 
components of a catalog, key-sequenced cluster, or alternate index. For 
example, you may wish to specify WRITECHECK for the data component 
and NOWRITECHECK for the index component or vice versa. 

The level at which you specify attributes can also be affected if you use the 
MODEL parameter of the DEFINE command (see "How to Use One Object 
as a Model for Another Object"). 



How to Use One Object as a Model for Another Object 






You can use the entry of an akeady-defined VSAM object (that is, an 
already-defined alternate index, catalog, cluster, or path) as a model for the 
definition of another object of the same type. When one entry is used as a 
model for another, its attributes are copied as the new entry is defined. 

You can override some of the model's attributes by expUcitly specifying them 
with the DEFINE command. If you do not want to change or add any 
attributes, you need only supply the entryname of the object being defined 
and the MODEL parameter. (When you define a catalog, you must also 
specify the catalog's volume and space information, because the catalog, 
when defined, owns the volume. When you define an alternate index or a 
path, you must also specify the object to which it is related.) 

• If MODEL is specified as a parameter of USERCATALOG, 
PAGESPACE, or PATH: 

- the attributes of the model are copied for the object being defined, then 

- any attributes expUcitly specified as parameters of your DEFINE 
command override those of the model. 

• If MODEL is specified as a parameter of CLUSTER or 
ALTERNATEINDEX (that is, at the cluster level) but is not specified as a 
subparameter of the DATA or INDEX parameter: 

- the attributes of the model are copied for the cluster or alternate index 
entry of the object being defined, then' 

- any attributes explicitly specified as parameters of CLUSTER or 
ALTERNATEINDEX override those of the model for the cluster or 
alternate index entry. 

- the attributes of the model's data and index components are copied for 
the object's data and index components, then 

- attributes explicitly specified as parameters of CLUSTER or 
ALTERNATEINDEX are propagated to the data and index 
components, overriding those of the model, then 

- attributes expUcitly specified for the object's data and index components 
(that is, specified as subparameters of the DATA or INDEX parameter) 
override the previous two steps. 
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• If MODEL is specified as a subparameter of DATA or INDEX as well as a 
parameter of CLUSTER or ALTERNATEINDEX: 

-. the attributes of the CLUSTER or ALTERNATEINDEX model are 
copied for the cluster or alternate index entry of the object being 
defined, then 

- any attributes explicitly specified as parameters of CLUSTER or 
ALTERNATEINDEX and override those of the model for the cluster or 
alternate index entry. 

- attributes explicitly specified as parameters of CLUSTER or 
ALTERNATEINDEX are propagated to the object's data and index 
components, then 

- attributes of the model specified for the data or index component are 
copied (that is, the model specified with the MODEL subparameter of 
the DATA or INDEX parameter), overriding the previous step, then 

- attributes explicitly specified for the data and index components are 
copied (that is, the attributes specified with subparameters of the DATA 
or INDEX parameter), overriding the previous two steps. 

The MODEL parameter is designed to let you easily define data sets that are 
essentially identical. By explicitly specifying certain parameters (for example, 
protection attributes), you can override any attributes of the model you wish 
to change. When you use the MODEL parameter, you should take care to 
ensure that your job is not terminated because of allocation problems when 
you explicitly do any of the following: 

• Specify a different type of device with the VOLUMES parameter, 

• Change the length or position of the keys with the KEYS parameter, 

• Change the size of records, buffer space, or control intervals with the 
RECORDSIZE, BUFFERSPACE, or CONTROLINTERVALSIZE 
parameters. 

• Change the type of cluster (that is, entry-sequenced, key-sequenced, or 
relative-record), the type of alternate index (that is, key-pointer or 
RBA-pointer), or the allocation-type of the object (that is, unique or 
nonunique), 

• Change the unit of allocation with the CYLINDERS, RECORDS, or 
TRACKS parameters. 

When you explicitly specify any of the above parameters for your 
to-be-defined object, you might have to make corresponding changes to other 
related parameters, , 



76 OS/VS2 Access Method Services 



Defining a Catalog 

The DEFINE command can be used to define user catalogs. 

A master catalog, which is the system catalog, is established at 
system-generation time. The volume on which the master catalog is defined 
must be permanently mounted. The master catalog is selected for use at initial 
program load (IPL) time. Because the master catalog is created at 
system-generation time and because only one master catalog is allowed on a 
system, you cannot issue DEFINE MASTERCATALOG to create a master 
catalog in a VS2 system. If you issue DEFINE MASTERCATALOG, VSAM 
creates a user catalog. You can, however, establish a user catalog as a. master 
catalog at IPL time. See "Appendix H: Changing the Attributes of the VSAM 
Master Catalog" for a description of this procedure. 

In a system with the Mass Storage System, a user catalog can be defined on a 
mass storage volume. If it is, it is staged and bound when it is opened (that is, 
it is retained until closed on the direct-access storage staging drive to which it 
is staged). A catalog can contain entries for both objects stored on mass 
storage volumes and objects stored on direct-access storage volumes. 

User catalogs are pointed to by the master catalog. The master catalog 
contains a user-catalog entry that identifies the user catalog's volume. Each 
user catalog resides on a different volume. All VSAM objects on a volume 
must be defined in the volume's user catalog. A user catalog can control (that 
is, catalog the objects of) more than one volume. 

When you define a user catalog, you can specify passwords for it even when 
the master catalog is not password-protected. To prevent an unauthorized 
user from deleting your user catalog, specify a password for it (the catalog's 
master password is required to delete it, but any password specified for the 
catalog results in a master password). (See the MASTERPW, 
CONTROLPW, UPDATEPW, and READPW descriptions.) 

You can delete a user catalog and redefine it in the same step, but you cannot 
use it in that step. A TSO session is considered one step so you would have to 
log off and log on to use a catalog that you had deleted and redefined. 

Haw Space Is Assigned to a Catalog 

The structure of a VSAM catalog is described in Planning for Enhanced 
VSAM Under OS /VS. Familiarity with this structure will be of help to you in 
understanding the discussion that follows. 

When a catalog is defined, the catalog is the first VSAM object contained on 
the volume. VSAM first builds a data space on the volume and then builds the 
catalog itself (see the section "Defining a Data Space" for further information 
about VSAM data spaces). You must specify the size of the data space by 
using the CYLINDERS, RECORDS, or TRACKS parameter as a 
subparameter of USERCATALOG. For example, 

DEFINE USERCATALOG - 
TRACKS ( prim seen ) . . .) 
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where: 

• TRACKS specifies the number of tracks to be allocated to the data space. 

You may optionally specify the size of the catalog itself by using the 
CYLINDERS, RECORDS, or TRACKS parameter as a subparameter of 
DATA, or DATA and INDEX. For example, 

DEFINE USERCATALOG - 

(TRACKS ( prim seen )...)- 
DATA- 

(RECORDS ( prec srec ) ...) 

where: 

• TRACKS specifies the number of tracks to be allocated to the data space. 

• RECORDS specifies the number of records to be contained in the low-key 
range of the catalog's data component (see the section "Estimating the 
Catalog's Space Requirements" for a discussion of this value). 

The data space is built for the catalog's exclusive use when the DATA and 
INDEX parameters do not include space subparameters. If the DATA or 
DATA and INDEX parameters do include space subparameters, part of the 
data space can contain suballocated VSAM data sets. 

To share the data space with other VSAM data sets, you can specify space for 
the data and, optionally, index components of the catalog. The space specified 
as a subparameter of DATA and INDEX determines the amount of space 
used by the catalog; the space specified as a subparameter of 
USERCATALOG determines the amount of space in the data space. If space 
is specified for the low-key range of the data component (using the DATA 
parameter) but not for the index component, VSAM determines the amount 
of space required for the catalog's data component high-key range, the 
sequence set, and for the index component. 

The following is a summary of the three ways in which space can be specified 
when defining a catalog. 

• If DATA space subparameters are not coded, the entire data space is 
available to contain catalog entries only. (INDEX space subparameters are 
invalid unless DATA space subparameters are also specified.) 

• If botli DA 1 A and INDEX space subparameters are coded, the sum of the 
space subparameters determines the amount of space available to contain 
the catalog. VSAM determines the proportion of this amount of space to 
be allocated to the catalog's data and index components. The remainder of 
the data space is available to contain suballocated VSAM data sets. 

• If DATA space subparameters are coded but INDEX space subparameters 
are not coded, the amount specified determines the size of the low-key 
range of the catalog's data component. VSAM then determines the amount 
of space required for the high-key range of the data component, the 
sequence set, and the high-level index and adds it to the DATA space 
subparameter specification. That is, VSAM determines the additional space 
needed based on the amount of space specified for the low-key range of 
the catalog's data component. The remainder of the data space (that is, the 
space that is not allocated to either the catalog's data or index 
components) is available to contain suballocated VSAM data sets. 

For example, if you specified, as a subparameter of USERCATALOG, 100 
cylinders of a 3330 Disk Storage Device (that is, the primary allocation for 
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the catalog's data space is 100 cylinders) and for the catalog's data and index 
components 5 cylinders (that is, the sum of the DATA and INDEX primary 
allocation amounts is 5 cylinders), 95 cylinders remain in the data space and 
are available for suballocated VSAM data sets. 

Catalog space is allocated in tracks (even when you specify cyhnders or 
records). The number of tracks is a multiple of an allocation unit. An 
allocation unit is the size of a control area, with one track for the control 
area's repUcated sequence-set record. The size of an allocation unit is: 

• 3 tracks for a 3330, 3330 model 11, 3350, or 2305 model 2 (2 tracks for 
the control area and 1 track for the sequence set record). 

• 4 tracks for a 2305 model 1 (3 tracks for the control area and 1 track for 
the sequence set record). 

• 5 tracks for 2314/2319 or 3340/3344 (4 tracks for the control area plus 1 
track for the sequence set record). 

When the amount of space you specify is not a multiple of the device's 
allocation unit, the amount of space is rounded downward to a multiple and 
the additional tracks are not used. If you specify less than the minimum 
allocation unit, the amount of space is rounded upward and a njinimum-sized 
catalog is allocated. 

One allocation unit is always allocated to the index set of the index. Ten 
percent of the remaining allocation units (or at least one allocation unit) is 
allocated to the high-key range of the data component. The rest of the 
allocation units are allocated to the low-key range. The minimum catalog size 
is three allocation units: one each for the index set, the high-key range, and 
the low-key range. 

For example, assume that one cylinder on a 3330 is specified for the entire 
catalog (1 cylinder =19 tracks): 

• The number of tracks is rounded down to 18 tracks, which is six allocation 
units of three tracks each (the nineteenth track is not used and not 
available unless the catalog's data space is suballocated). 

• One allocation unit (three tracks) is allocated to the catalog's index set. 

• Because 10% of the remaining 15 tracks is less than three tracks, one 
allocation unit is allocated to the high-key range of the data component. 

' The first track contains a repUcated sequence-set record. The next two 
tracks contain a control area with 40 control intervals, which can hold a 
maximum of 400 records. (Records in the high-key range are 47 bytes 
long.) 

• The remaining four allocation units (12 tracks) are allocated to the low-key 
range of the data component. Each allocation unit includes one track for 
the replicated sequence-set record and two tracks for a control area with 
40 control intervals, which can hold 40 records. (Records in the low-key 
range are 505 bytes long.) The low-key range can hold a maximum of 160 
records. From 12 to 15 of these records (13 for a 3330) are used to 
describe the catalog itself. 

When the maximum number of records is reached in the low-key or high-key 
range, the catalog must be extended to hold additional records. When you 
define the catalog, you can specify an amount of space for secondary 
allocation. 
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Identifying the Catalog's Volume 



When you define a catalog, you can use a JCL DD statement to identify and 
mount the volume on which the catalog is to reside. Instead of using a JCL 
DD statement, you can rely on dynamic allocation to identify the catalog's 
volume. The volume must be mounted as permanently resident or reserved. If 
JCL is used, include a DD statement of the form: 

//ddname DD DISP=OLD,UNIT=( type [ „DEFER ] ), 
// VOLUME=SER=5ma/ 

The volume on which the catalog and its data space are to be allocated must 
be mounted, because the data space must be described in a data-set control 
block (DSCB) that is stored in the volume's VTOC (volume table of 
contents). The DSCB is added to the VTOC and the volume-ownership 
information, also in the VTOC, is reset to indicate that the volume is owned 
by a VSAM catalog. VSAM determines whether the space is available on the 
volume and, if so, formats a DSCB for the data space. 



NonVSAM Data Sets and the Catalog's Update Password 



When you expect the user catalog to contain nonVSAM data sets, you should 
take care when you specify passwords for the catalog. When you specify an 
update password for the catalog. Access Method Services requires that you 
supply the password whenever you (or another user) want to alter or delete 
one of the catalog's nonVSAM data sets. You can protect the catalog against 
unauthorized usage by specifying a master password. See the UPDATEPW 
description under DEFINE USERCATALOG for more details about how a 
catalog's update password is used. 



Estimating the Catalog's Space Requirements 



Before you define a catalog, you should estimate the amount of space needed 
for the catalog's data component. To determine the approxiriiate number of 
records required for the low-key range of the catalog, use the worksheet in 
Figure 3: 

When you define the catalog's space parameters, you may use one of the 
formats shown below: 

L If you wish to assign all of the space to the catalog itself, you may specify: 

DEFINE USERCATALOG - 
(TRACKS ( prim seen )... ) 

where: 

• prim = the amount of space for the primary extent (that is, allocation) 
of the catalog's data space. You can calculate the minimum value of 
prim as: 

prim = (aN + b) tracks 
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Variable Quantities 


Formulas 


Estimates 


Basic requirement = 10 records 

A = number of key-sequenced clusters 

A = number of key-sequenced clusters with alternate 
indexes to be upgraded 

B = number of entry-sequenced clusters 

B = number of entry-sequenced clusters with alternate 
indexes to be upgraded 

C = number of relative-record clusters 

D = number of alternate indexes 

E = number of path entries 

F = number of nonVSAM data set entries 

G = number of generation data group entries 

H = number of alias entries 

I = number of pagespaces 

J = number of volumes, depending on device type, 
owned by the catalog; 
J ' = number of 2305 volumes 
j2 = number of 2314/2319 volumes 
j3 = number of 3330 and 3340/3344 volumes 
J^ = number of 3330 Model 1 1 and 3350 volumes 

K = for each key-sequenced cluster and alternate index 
(KSDS) with space on more than two volumes, 
add "1" for each additional group of one to five 
volumes: 

K^ = number of KSDSs with 3 to 7 volumes 
k2 = riumber of KSDSs with 8 to 12 volumes 
k3 = nfimber of KSDSs with 1 3 to 1 7 volumes 

L = for each entry-sequenced cluster and relative-record 
cluster (ESDS) with space on more than five volumes, 
add "1" for each additional group of one to eight 
volumes: 

L* = number of ESDSs with 6 to 13 volumes 
l2 = number of ESDSs with 14 to 21 volumes 

M = for each group of four data spaces on a volume, 
add'T' 

N = number of entry records required for the catalog's 
data component (total of A through M above) 


Ax3 
a'x4 

Bx2 
B»x3 

Cx2 

Dx3 

E 

F 

G 

H 

1*2 
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Kl 

K2x2 

k2x3 

O 
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Figure 3. Worksheet for Estimating a Catalog's Space Requirements 

where N is the value derived from the worksheet (Figure 3) and the 
values of a and b are derived from the table below: 



Catalog resides on: 


a 


b 


2305 Model 1 


0.1 


5 


2305 Model 2 


0.09 


3 


2314 or 2319 


0.1364 


5 


3330 or 3330-11 


0.09 


3 


3340 or 3344 


0.125 


5 


3350 


0.0667 


3 



The calculated value of prim should be rounded upward to a whole 
number of tracks. 

seen = the amount of space for each secondary extent of the catalog's 
data space. 
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This example shows the space specification in terms of TRACKS using 
the worksheet in Figure 3. You may also specify the value for prim and 
seen as a subparameter of CYLINDERS. 

2. If you wish to have other VSAM objects in the catalog's data space, 
you may specify: 

DEFINE USERCATALOG - 

(TRACKS ( prim seen )...)- 
DATA - 

(RECORDS ( pree sree ...) 

where: 

• pree = the number of catalog entry records in the low-key range, or the 
value of N from the worksheet (Figure 3). VSAM uses this value to 
calculate the total primary allocation requirements for the catalog itself. 

• sree = the number of catalog-entry records to be used by VSAM to 
calculate the catalog's secondary-extent allocation. 

• prim = the total amount of space for the primary extent of the catalog's 
data space. The amount of space assigned to the catalog itself is taken 
from the prim space as calculated by VSAM from the value specified by 
pree. You can determine the amount of space that VSAM calculates for 
the catalog itself using the following algorithm: 

(aN + b) tracks 

as described for format- 1 above. When you specify a value for prim 
larger than the requirements for the catalog itself, the remainder of the 
space is available for the subaUocation of other VSAM objects. Using 
this format, you may also specify the value for prim as a subparameter 
of CYLINDERS rather than TRACKS. 

• seen = the amount of space to be used for each secondary extent of the 
catalog's data space. 



The Catalog's Secondary Allocation Amount 



You should specify a secondary allocation amount for the catalog's data 
component. You cannot use the ALTER command to add or change a 
secondary allocation amount once the catalog is defined. 

The secondary allocation quantity is allocated each time one of the catalog's 
key ranges needs more space — up to a total of thirteen times. The secondary 
allocation quantity you specify for the catalog's data component appUes to the 
catalog's high-key range and low-key range (including their sequence set 
tracks). When the high-key range or low-key range runs out of space, the 
specified secondary allocation quantity is allocated to the key range that 
requires the space (when both key ranges run out of space at the same time, 
two separate extents are allocated: one for each key range, and each equal to 
the secondary allocation quantity). 

You use the secondary allocation to minimize the size of the low-key range 
and to provide for an extension of the high-key range: after the catalog's 
index set is allocated, 10% of the remaining space (or one allocation unit, 
whichever is larger) is allocated to the high-key range; the remainder of the 
catalog's space is allocated to the low-key range. However, the high-key range 
might achieve only 25% utilization. Rather than specify a primary allocation 
quantity large enough to allow for low utilization of the high-key range and, 
therefore, create an unnecessarily large low-key range, you can specify a 
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secondary allocation. The secondary allocation quantity is allocated to the 
high-key range when it requires space, without affecting the size of the 
low-key range. (The same applies to the low-key range, when it requires 
space.) 

The high-level index of a catalog never requires extension. 

Space Allocation for the Catalog Recovery Area (CRA) 

Whether or not a catalog is defined with the RECOVERABLE option has a 
bearing on how space is assigned in the catalog. For a recoverable catalog, 
VSAM creates a catalog recovery area (CRA) on each volume owned by the 
catalog. The primary allocation for a CRA is the number of tracks equivalent 
to one cylinder. VSAM ensures that these tracks are contiguous, but they may 
or may not start on a cylinder boundary. On the volume on which the catalog 
resides, the primary allocation for the CRA is allocated from the catalog's 
data space. 

On volumes without a VSAM catalog, a primary space allocation is obtained 
by VSAM for the CRA when the first data space is defined on the volume. If 
the first data space is defined via the UNIQUE attribute of DEFINE 
CLUSTER or ALTERNATEINDEX, VSAM obtains one cylinder of space 
on the volume for the CRA. In other words, the CRA's primary allocation is 
added to the space specified via space parameters (CYLINDERS, 
RECORDS, or TRACKS) of your DEFINE command. 

If the first data space is defined via DEFINE SPACE, VSAM first attempts to 
obtain space for the CRA's primary allocation as before. However, if VSAM 
fails to obtain the space, the CRA will be allocated from the space specified 
via the space parameters. If the fkst DEFINE SPACE for a volume specifies 
the CANDIDATE attribute, VSAM obtains one cylinder for the CRA's 
primary allocation. 

Once a primary allocation of the CRA is fiUed, it can expand to include a 
maximum of fifteen additional extents. The allocation for each secondary 
extent is one cylinder. 



Defining a Date Space 



The DEFINE command can be used to define VSAM data spaces or to 
reserve volumes for future VSAM use. 

Refer to the chapter: "Command Format" for a description of the command 
format for DEFINE SPACE. An example of defining a VSAM data space is 
also included. 



VSAM Data Spaces on a Volume 



A VSAM data space is space on a direct access volume that is owned and 
managed by VSAM (as opposed to space managed by OS/VS using 
Direct- Access Device Space Management — ^DADSM). All of the data spaces 
(and VSAM data sets) on a volume are defined in the same VSAM catalog. 
When you define the volume's first data space (or you specify the volume as a 
candidate to contain VSAM objects) you are, in effect, giving control over 
the volume to the catalog that contains the data space entry. All future data 
spaces and VSAM objects on that volume must be defined in the defining 
catalog (that is,- the catalog that describes the volume's first-defined data 
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space). Remember that when you define a catalog you cause the fust data 
space to be defined on the catalog volume. 

A VSAM data space may include several extents on the same volume, but it 
cannot span volumes. The volume that contains the data space is owned by 
the catalog that contains the catalog entry for the space. A VSAM data space 
can take up all or part of the space of a direct-access volume. It cannot take 
up space on more than one volume. There can be more than one data space 
on a volume. In a system with the Mass Storage System, a data space can be 
defined on a mass storage volume. 

When you define a data space, you must specify the volume that is to contain 
the data space. When you specify more than one volume, a data space of the 
size you specify is allocated on each volume; each volume comes under the 
control of the defining catalog. Access Method Services creates a volume 
entry in the catalog to describe each volume on which one or more data 
spaces have been defined. 

If there is space available and there is no volume ownership conflict, a VSAM 
data space is allocated on the volume. When the data space is the first data 
space on a volume , VSAM ownership is indicated in the VTOC. The volume's 
VTOC is modified so that an ownership indicator is set in the format-4 
DSCB. A format- 1 (identifier) DSCB describing the data space is also written 
into the VTOC. When the data space is the first data space on a volume 
owned by a recoverable catalog, VSAM also allocates a recovery space on the 
volume. Refer to "Space Allocation for the Catalog Recovery Area (CRA)" 
for more information on CRA space allocation. 



You can use a DD statement to allocate the volume on which the data space is 
to be defined. If you do not use a DD statement to allocate the volume, the 
volume identified with the VOLUMES parameter is dynamically allocated. 
The volume must be mounted as permanently resident or reserved. ' 

When you use a DD statement to allocate the volume on which the data space 
is to be defined, it should be in the form: 

//ddname DD DISP=OLD, 

// UNIT=( devtype [ , unitcount ][ ,DEFER ] ) , 

// VOLUME=3ER=( volseri [, volser2 ,...]) 



VSAM Objects in a Data Space 



All VSAM objects (that is, catalogs, clusters, alternate indexes, and page 
spaces) are stored in VSAM data spaces. A unique component is defined as 
the only component in its data space. VSAM allocates the data space for a 
unique component when you define the data set. A nonunique object can 
share a data space with other VSAM objects. That is, a catalog, clusters, page 
spaces, and alternate indexes might also be in the data space. To define a data 
set that can share a data space with other data sets, a data space must have 
been defined beforehand in which to subaUocate space for the data set. 

A data space can contain many nonunique data sets, and a data set can be 
stored in more than one data space, on the same volume or on different 
volumes. 
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Space Assignment to VSAM Objects 



Defining a Cluster 



\ 



When VSAM allocates space for a new data set or extends the space for an 
existing data set, it allocates the space from that available in a data space. For 
a new data set, if not enough space is available, the DEFINE fails, and you 
must define a data space with sufficient space. 

For an existing data set, if not enough space is available, VSAM tries to 
extend the data space. If the data space cannot be extended (it may already 
have the maximum number of extents or there may not be enough space on 
the volume), VSAM tries to set up a new data space on the same volume as 
the old. 

If the data space cannot be extended because a suballocated data set's 
secondary allocation amount is greater than the data space's secondary 
allocation amount, VSAM builds a new data space: its primary and secondary 
allocation amounts are the same as the data set's secondary allocation 
amount. Consequently, the total amount of space allocated to VSAM data 
spaces on a volume might exceed the predicted limit. If there is not enough 
space on the volume and you identified another volume for expansion when 
you defined the data set, VSAM tries to set up a data space on that volume. 



The DEFINE command can be used to define a catalog entry and allocate 
space for an indexed, nonindexed, or relative-record cluster. When a DEFINE 
command is used to define a cluster, as many as three entries are created in 
the catalog: an entry for the cluster, its data component, and, if the cluster is 
indexed, its index component. 

Attributes of components can be specified separately from the attributes of 
the cluster. If attributes are specified for the cluster as a whole and are not 
specified for the components, the attributes of the cluster (except for its 
passwords and other protection attributes) apply to its components. If an 
attribute that is applicable to the data or index component is specified for 
both the cluster and the component, the explicit component specification 
overrides that specified for the cluster. 

You specify a name for the cluster when you define it and generally give this 
name as the dsname in JCL. You can optionally name the components of a 
cluster. You may wish to name the data component of an entry-sequenced 
cluster or the data and index components of a key-sequenced cluster in order 
to make it easier to process them individually. For instance, you may open the 
index of a key-sequenced data set and process it as data. This processing is 
described in OS/VS Virtual Storage Access Method (VSAM) Options for 
Advanced Applications. If you wish to use the ALTER command to modify 
attributes of any component, you must identify that component by name. If 
you do not specify a name for the components of a cluster, VSAM generates 
a name in the form: 

VSAMDSET.Tbbbbbbb.DFDyyddd.Taaaaaaa.Tbbbbbbb 

where: 

- yyddd is the date (year and Julian day) 

- aaaaaaabbbbbbb is the timestamp value 



Creating and Cataloging Objects 85 



Refer to the chapter "Command Format" for a description of the command 
format for DEFINE CLUSTER. Examples of defining clusters are also 
included. 



Specifying Cluster Information 



Descriptive Information 



You specify all of the necessary descriptive informatioti and the performance, 
security, and integrity options when you create a cluster. Some of the 
information you specify can apply to either the data or the index or to both. 
You can specify information for the cluster as a whole in the CLUSTER 
parameter. Information for data only or for index only goes with the 
corresponding parameter (DATA or INDEX). 



Descriptive information includes: 

• Type of data organization 

• Whether the cluster is reusable (that is, for temporary storage of data) 

• Average and maximum lengths of data records 

» Length and position of the key field in the records of a key-sequenced data 
set 

• Identity of the catalog in which to define the cluster 

• Identity of the volume(s) on which to allocate space for the cluster 

• Amount of space to allocate for the cluster and whether the cluster is to 
reside in a separate data space 

• Least amount of I/O-buffer space a processing program will provide to 
process the data set 

With a multivolume key-sequenced data set, you may assign data to the 
various volumes according to ranges of key values. For example: if you have 
three volumes you might assign records with keys A-E to the first volume, 
F-M to the second, and N-Z to the third. Key-range allocation facilitates 
processing the data set with only one of the volumes mounted: you know 
which volume contains what records. AH of the volumes specified for the 
cluster's data component or for the index coiuipGncOt musl be of the same 
device type. However, the data component's device type can be different than 
the index component's device type. 

If a component is unique (that is, is to reside alone in a separate data space), 
the data space is not defined before the cluster is defined. The data space is 
created as the cluster is defined; in this case, the volume(s) must be mounted. 

If you don't specify the space to be provided for buffers, VSAM determines 
control interval size first and then sets buffer-space amount equal to the size 
of two data control intervals plus, for a key-sequenced data set, one index 
control interval. If you do specify it, data and index control intervals are 
limited to sizes such that the buffer space can hold two data control intervals 
and one index control interval. 

If the values you specify for record length and key length require control 
intervals too large for the buffer space you specify, the DEFINE command 
will fail. 

The relationship between control interval size and least amount of I/O-buffer 
space is further discussed in OS/VS Virtual Storage Access Method (VSAM) 
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Programmer's Guide. If you specify track allocation or specify record 
allocation for less than one cylinder, space is actually allocated by tracks. 

Performance Options Information 

Information for performance options (mostly for an indexed cluster) include: 

• Whether records can span control intervals 

• Whether to replicate index records 

• Whether to place the sequence set of an index adjacent to data 

• Whether to place the cluster's index on a separate volume from data 

• The amount of free space to remain in the data component's control 
intervals and control areas when the data records are loaded (applies only 
to a key-sequenced cluster's data component) 

• Control interval size for VSAM to use instead of calculating the size itself 

These options are discussed in OS/VS Virtual Storage Access Method 
(VSAM) Programmer's Guide. 

In a system with the Mass Storage System, you can also indicate how a cluster 
or component that is stored on a mass-storage volume is to be staged. 

Protection and Integrity Information 

Information for protection and integrity options include: 

• Passwords and related information 

• Identity of your own authorization routine to verify that a requester has 
the right to gain access to data 

• Identity of an I/O error-handling routine (the exception exit routine) that 
is branched to before the program's SYNAD exit is taken 

• Whether to pref ormat control areas during data record insertion 

• Whether to verify that write operations are without error 

• Whether and to what extent to share data among systems, jobs, and 
subtasks 

• Whether to erase the information that a data set contains when you delete 
the data set 

These options are discussed in the chapter "Data Security and Protection" 
and in Planning for Enhanced VSAM Under OS/VS. 

In a system with the Mass Storage System, you can also indicate whether a 
cluster or component that is stored on a mass storage volume is to be 
destaged synchronously or asynchronously with respect to the program that 
closes it. 
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Defining an Alternate Index 



An alternate index can be defined over a key-sequenced cluster or over an 
entry-sequenced cluster. An alternate index cannot be defined to support a 
reusable cluster, a relative-record cluster, a catalog, another alternate index, 
or a nonVSAM data set. 

Before you can build an alternate index, you must define and load its base 
cluster (see the DEFINE CLUSTER command), then define the alternate 
index and relate it to the base cluster. The base cluster and alternate index are 
described by entries in the same catalog. 

You can issue the DEFINE ALTERNATEINDEX conmiand to define an 
alternate-index entry and allocate space for an alternate index. VSAM uses 
more than one catalog entry to describe the alternate index (an alternate 
index is conceptually a key-sequenced cluster): 

• An alternate-index entry describes the alternate index as a key-sequenced 
cluster. 

• A data entry describes the alternate index's data component. 

• An index entry describes the alternate index's index component. 

Attributes of the alternate index's components can be specified separately 
from the attributes of the alternate index. When attributes are specified for 
the alternate index as a whole and are not specified for the components, the 
attributes of the alternate index (except for its passwords and other protection 
attributes) are propagated to the alternate index's components. The attribute 
specified for the component overrides that specified for the alternate index. 

When you define the alternate index, you identify it with an entryname. The 
entryname identifies the alternate index when it is described with a JCL DD 
statement (that is, the entryname is the JCL DD statement's dsname) and 
when it is processed with another Access Method Services command. You can 
also name the alternate index's components; a user's program can open and 
process the alternate index's data or index component as a data set. For 
example, your program can open the index of an alternate index, then read 
and write its records. For more details on this kind of processing, see OS/ VS 
Virtual Storage Access Method (VSAM) Options for Advanced Applications. 

Refer to the chaptci "Cummand Format" tor a description of the command 
format for DEFINE ALTERNATEINDEX. An example of defining an 
alternate index is also included. 



Specif ^ng Alternate-Index Information 



When you define an alternate index, you specify descriptive information and 
performance, security, and data-integrity options. Some of the information 
you specify can apply to either the alternate index's data component, or to its 
index component, or to both — that is, to the alternate index as a whole. You 
specify information for the alternate index as a whole with the 
ALTERNATEINDEX parameter and its subparameters. Information for the 
data component or for the index component is specified with parameters of 
DATA or INDEX. 
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Descriptive Information 



Information that you specify to describe the alternate index being defined 
includes: 

• The base cluster related to the alternate index. 

• Whether the alternate index is reusable (that is, temporary). 

• Average and maximum lengths of alternate-index records. 

• Length and position of the key field in data records of the alternate index's 
base cluster. 

• Identity of the catalog that is to contain the alternate index's entries (the 
same catalog that contains the base cluster's entries). 

• Identity of the volume(s) on which space is to be allocated for the alternate 
index. 

• Amount of space to allocate for the alternate index and whether the 
alternate index is to reside in a separate data space. 

• The least amount of I/O buffer space that a user's program is to provide 
when the program processes the alternate index's data. 

You can define an alternate index with its records assigned to various volumes 
according to alternate-key value. Each volume can contain the alternate-index 
records whose alternate key values are between a low-key value and a 
high-key value — ^that is, records whose alternate-key values are within a key 
range. For example, your alternate index might reside on three volumes. The 
records with alternate keys A through E are on the first volume, F throu^ M 
on the second volume, and N through Z on the third volume. 



Performance Options Information 



Information that you can specify to improve the performance of your 
alternate index include: 

• Control-interval size, instead of allowing VSAM to calculate an optimum 
size. 

• Whether to place the index's sequence set adjacent to the data control 
areas. 

• Whether to place the alternate index's index on a separate volume (or 
direct-access device) from the alternate-index records. 

• The amount of free space to remain in the data component's control 
intervals and control areas when the alternate-index records are loaded 
(applies only to the alternate index's data component). 

These options are discussed in OS/VS Virtual Storage Access Method 
(VSAM) Programmer's Guide. 

In a system with the Mass Storage System, you can also indicate how an 
alternate index or component that is stored on a mass-storage volume is to be 
staged. 



Protection and Integrity Information 



Information that you can specify to protect your alternate index's records 
from other users and from possible system errors include: 

• Passwords and related user-verification information. 
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• Identity of your authorization routine to verify that a user's program is 
authorized to gain access to the alternate index's records. 

• Identity of your I/O error-handling routine (the exception exit routine) 
that is branched to before the program's SYNAD exit is taken. 

• Whether to preformat control areas before the alternate-index records are 
loaded. 

• Whether, and to what extent, to share your alternate index between 
subtasks, jobs, and systems. 

• Whether to erase the information that your alternate index contains when 
you delete it. 

These options are discussed in "Data Security and Protection" and in 
Planning for Enhanced VSAM Under OS /VS. 

In a system with the Mass Storage System, you can also indicate whether an 
alternate index or component that is stored on a mass-storage volume is to be 
destaged synchronously or asynchronously with respect to the program that 
closes it. 



The DEFINE PATH command is used to establish the relationship, the path, 
between an alternate index and its base cluster. The base cluster and its 
alternate index must already be defined when you define the path that relates 
them. 

When your program opens a path for processing, both the alternate index and 
its base cluster are opened. When data in the base cluster is read or written 
using the path's alternate index, keyed processing is used; RBA processing is 
not allowed. 

You can also use the DEFINE PATH command to establish a 
password-protected alias for a VSAM cluster. The cluster must already be 
defined when you define a path as its alias. The path entry, as an alias, allows 
the cluster another set of protection attributes. You can specify NOUPDATE 
access for the cluster, which aUows you to open the cluster without also 
opening its upgrade set (that is, all of the cluster's alternate indexes that are 
to be updated whenever the cluster's data is changed). 

Refer to the chapter "Command Format" for a description of the command 
format for the DEFINE PATH command. An example for defining a path is 
also included. 
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Defining a NonVSAM Data Set 



The DEFINE command can be used to catalog a nonVSAM data set in a 
VSAM catalog. Any already existing nonVSAM data set can be introduced 
into a master or user catalog through the DEFINE command. The result of a 
DEFINE command when it is used to define a nonVSAM entry is that an 
entry is created in a master or user catalog; no space is allocated or reserved. 

When you define, alter, or delete a nonVSAM data set in a 
password-protected catalog, the catalog's update- or higher-level password is 
required. 

Refer to the chapter "Command Format" for a description of the command 
format and an example of the DEFINE NONVSAM command. 



Defining an Alternate Name 



The DEFINE command can be used to define an alternate name — an 
alias — for a nonVSAM data set (even if it is a generation data set). DEFINE 
ALIAS can also be used to define an alias for a user catalog connector in the 
master catalog. An alias cannot, however, be defined for a generation data 
group. 

Refer to the chapter "Command Format" for a description of the command 
format for DEFINE ALIAS. An example is also included. 



Haw to Use an Alias to Identify a User Catalog 



When you define an alias for a user-catalog connector, you should structure 
the alias so that the catalog's cataloged data sets can be located when the alias 
is used. If ySAM is searching^ for a user-specified entryname (that identifies 
a data set) and does not find its entry in the master catalog or a user catalog 
identified with the JOBCAT or STEPCAT DD statements, and if the 
entryname's catalog is not specified, VSAM assumes that: 

• The entry resides in a user catalog, and 

• The user-catalog's name or alias is the first simple name of the qualified 
entryname. 

If the entryname is ABC.DE.DATA, VSAM searches the master catalog for a 
user-catalog connector entry (that is, an entry with the name or alias of 
ABC). If found, VSAM next searches catalog ABC for an entry identified by 
the name or alias ABC.DE.DATA. 

If you identify a catalog with a name of ABC.DE and catalog the entry whose 
name is ABC.DE.DATA in that catalog, the catalog won't be found when 
VSAM searches for it. In order for VSAM to find the entryname 
ABC.DE.DATA (an entry in the catalog whose name is ABC.DE), the 
catalog's name, ABC.DE, must also be specified (either explicitly in the 
Access Method Services command that refers to data set ABC.DE.DATA, or 
as a JOBCAT or STEPCAT DD statement). 

You can delete the alias of a user catalog and redefine it in the same step, but 
you cannot use it in that step. A TSO session is considered one step, so you 



1 For a detailed description of, and the correct search 
sequence for, how VSAM searches catalogs to locate 
an entry, see the section "Order of Catalog Use" for 
the various commands. 



Creating and Cataloging Objects 91 



would have to log off and log on to use an alias of a user catalog that you had 
deleted and redefined. 



Defining a Generation Data Group 



Defining a Page Space 



The DEFINE command can be used to create a catalog entry for a generation 
data group. For further information on generation data groups, see OS/VS2 
MVS Data Management Services Guide. 

Once a catalog entry for a generation data group has been created, existing 
data sets can be attached to it as generation data sets. This is accomplished 
through JCL, in the form DSNAME=name(n) (where n is the generation 
increment), or by defining each data set as a nonVSAM data set with a 
generation data set name, as follows: 

name . Gnnnn Vnn 

If the name is found to match the name of a previously defined generation 
data group, the nonVSAM data set is associated with the generation data 
group as a generation data set. See "Defining a NonVSAM Data Set" for a 
description of how to define a nonVSAM entry. 

When you create a generation data group it can be cataloged in a VSAM 
catalog. The model DSCB must exist on the generation data group's catalog 
volume. To create a generation data group in an OS CVOL, you can use the 
BLDG function of the OS/VS utility, lEHPROGM. All JCL specifications 
avaUable to support generation data groups work on VS2 Release 2 and later 
releases in a way equivalent to OS/MVT, VS2 Release 1, or VS2 Release 1.6, 
whether the generation data group is cataloged in a VSAM catalog or in an 
OS CVOL. 

Refer to the chapter "Command Format" for a description of the command 
format for DEFINE GENERATIONDATAGROUP. An example is also 
included. 



The DEFINE command can be used to define an entry for a page space. A 
page space is an OS/VS2 system data set that contains pages of virtual 
storage; the pages uic stored into and retrieved from the page space by the 
Auxiliary Storage Manager. A page space is a nonindexed data set (that is, an 
entry-sequenccd cluster) that is entireiy pre! ormatted before it is used. In a 
system with the Mass Storage System, a page space cannot be defined on a 
mass-storage volume. A page space must reside on a single volume. A page 
space cannot be opened as a user data set, 

A page space has a maximum usable size equal to 65,535 paging slots 
(records). See the description for space size declarations (CYLINDERS, 
RECORDS, and TRACKS for DEFINE PAGESPACE) in the "Command 
Format" chapter for further details. 

You can define a page space in a user catalog, then move the catalog to a new 
system and establish it as the system's master catalog. When you define a 
page space in a user catalog, you must also code a STEPCAT or JOBCAT 
statement to identify and allocate the catalog. 

When you issue a DEFINE PAGESPACE command, the system creates an 
entry in the catalog for the page space, and then preformats the page space. If 
an error occurs during the Preformatting process (for example, an I/O error 
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or an allocation error), the page-space entry in the catalog exists even though 
no space for it exists. You must issue a DELETE command to remove the 
page-space entry before you redefine the page space. 

Each page space is represented by two entries in the catalog: a cluster entry 
and a data entry (that is, a page space is conceptually an entry-sequenced 
cluster.) Both of these entries should be password protected if the page space 
is to be password protected. (Note: The passwords you specify with the 
DEFINE PAGESPACE command are put in both the page space's cluster 
entry and its data entry.) When you define page spaces during system 
generation (SYSGEN), you should use the ALTER command to add 
passwords to each entry, since passwords cannot be specified during system 
generation. 

In addition, you should ensure that the catalog containing the page-space 
entry is password protected. Otherwise, a user can Ust the catalog's contents 
and find out each entry's passwords. 

A page space is made known to the system as a system data set at 
system-generation time or through members of a partitioned data set: 
SYSl.PARMLIB. To be used as a page space, a page space must have been 
defined in a catalog that is currently being used as the master catalog (that is, 
a page space cannot be used if its entry is in a user catalog). 

A page space's passwords and protection attributes are cataloged in both the 
page-space entry and its data-component entry. You should specify master, 
control, update, and read passwords to prevent the page space from being 
accessed if its volume is moved to a VSl system. The VS2 system 
automatically prevents a user's program from accessing a page space or its 
data component. 

Refer to the chapter "Command Format" for a description of the command 
format of DEFINE PAGESPACE. Examples of how to define page spaces 
are also included. 
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BUILDING AN ALTERNATE INDEX 



The BLDINDEX command is used to build an alternate index. Before you 
can build an alternate index, you must define and load its base cluster (see the 
DEFINE CLUSTER command), then define the alternate index and relate it 
to the base cluster (see the DEFINE ALTERNATEINDEX command). The 
base cluster and alternate index are described by entries in the same catalog. 

The alternate index's volume and the base cluster's volume must be mounted 
during the build process. Any volumes identified with the WORKFILES 
parameter must also be mounted. 

An alternate index can be built for a key-sequenced cluster or for an 
entry-sequenced cluster. The base cluster must be nonempty (that is, its 
high-used RBA value cannot be zero). An alternate index cannot be built to 
support an empty or reusable cluster, a relative-record cluster, a catalog, 
another alternate index, or a nonVSAM data set. 

Each of the base cluster's data records must be long enough to contain the 
alternate key. Each record's alternate-key value must be unique, unless the 
alternate index was defined with the NONUNIQUEKEY attribute. 

Refer to the chapter "Command Format" for a description of the command 
format for BLDINDEX. Examples of the BLDINDEX command are also 
included. 



Haw an Alternate Index is Built 



When an alternate index is built by BLDINDEX processing, Access Method 
Services opens the base cluster to sequentially read the data records, sorts the 
information obtained from the data records, and buUds the alternate-index 
records: 

1. The base cluster is opened for read-only processing. You can prevent other 
users from updating the base cluster's records during BLDINDEX 
processing by including the DISP=OLD parameter in the base cluster's DD 
statement. If INDATASET is specified. Access Method Services will 
dynamically allocate the base cluster with DISP=OLD. 

2. The base cluster's data records are read and certain information is 
extracted to form the key-pointer pair: 

• When the base cluster is entry-sequenced, the alternate-key value and 
the data-record's RBA form the key-pointer pair. 

• When the base cluster is key-sequenced, the alternate-key value and the 
data-record's prime-key value form the key-pointer pair. 

If the base cluster's data records can span control intervals, the alternate 
key must be in the record's first segment (that is, the first control interval). 

3. The key-pointer pairs are sorted in ascending alternate-key order. If your 
program provides enough virtual storage. Access Method Services performs 
an internal sort (that is, the sorting of key-pointer pairs takes place entirely 
within main, or virtual, storage). 
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You can detemiine the amount of virtual storage required to sort the 
•records internally by using the following process: 

a. Sort record length = alternate key length + (prime key length (for a 
key-sequenced data set) or 4 (for an entry-sequenced data set)). 

b. Record sort area size = sort record length x number of records in base 
cluster, rounded up to the next integer multiple of 2048, or 32,768, 
whichever is greater. 

c. Sort table size = (record sort area size -4- sort record length) x 4. 

The sum of b and c above is the required amount of virtual storage for an 
internal sort. This amount is in addition to the normal storage requirements 
for processing an Access Method Services command. 

If you do not provide enough virtual storage for an internal sort, or when 
you specify the EXTERNALSORT parameter, Access Method Services 
defines and uses two sort workfiles and sorts the key-pointer pairs 
externally. Access Method Services uses the sort workfiles to contain most 
of the key-pointer pairs while it sorts some of them in virtual storage. This 
process is called an external sort. An external-sort workfile is a VSAM 
entry-sequenced cluster, marked reusable, with space suballocated from a 
VSAM data space. The minimum amount of virtual storage you will need 
for an external sort is: 

32,768 + ((32,768 4- sort record length) x 4) 

The amount of space that Access Method Services requests when defining 
each sort workfile is calculated as follows: 

a. Sort records per block = 2041 -f- sort record length 

b. Primary space allocation in records = 

(number of records in base cluster -r- sort records per block) + 10 

c. Secondary space allocation in records = 

(Primary space allocation x 0.10) + 10 

Both primary and secondary space allocation are requested in records with 
a fixed-length record size of 2041 bytes and a control interval size of 2408 
bytes. 

4. When the key-pointer pairs have been sorted into ascending alternate-key 
order. Access Method Services builds an alternate-index record for each 
key-pointer pair. If the alternate index is defined with the 
NONUNIQUEKEY attribute and more than one key-pointer pair have the 
same alternate-key values, the alternate-index record that is built contains 
the alternate-key value followed by the pointer values in ascending order. 
If the alternate index is defined with the UNIQUEKEY attribute, each 
alternate-key value is unique. 

When the record is built, it is written into the alternate index as though it is 
a data record being loaded into a key-sequenced cluster. Attributes and 
values that apply to the loading of data records can be specified when the 
alternate index is defined and are: RECORDSIZE, 
CONTROLINTERVALSIZE, BUFFERSPACE, FREESPACE, 
WRITECHECK, SPEED, RECOVERY, REPLICATE, and IMBED. 

5. When all alternate-index records have been built and loaded into the 
alternate index, both it and its base cluster are closed. Steps 1 through 4 
are repeated for each alternate index that is specified with the OUTFILE 
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or OUTD AT ASET parameter. When all alternate indexes have been buUt, 
if external sort workf iles have been defined, they are deleted. Access 
Method Services finishes processing and issues messages that indicate the 
results of the processing. 



DD Statements That Describe the SORT Workf iles 



You can identify VSAM data space that the sort routine can use by specifying 
two dnames with the WORKFILES parameter and supplying two DD 
statements that describe the workf iles to be defined by Access Method 
Services. Each workfile DD statement should be coded: 

//ddname DD DSNAME= dsname, VOL= SER= vober, 
II UNrr=^evry/>e,DISP=OLD,AMP=*AMORG' 

ddname 

As specified in the WORKFILES parameter. If you do not specify the 
WORKFILES parameter and you intend to provide VSAM data space for 
external-sort workfiles, you identify the workfile DD statements with the 
names IDCUTl and IDCUT2. 

dsname 

A data set name. The OS/VS Scheduler generates a data set name for the 
workfile if none is provided. 

VOL=SER=vo/ser 

Required. Identifies the volume owned by the STEPCAT, JOBCAT, or 
master catalog in which the workfile is to be cataloged. The workfile's 
space is suballocated from the volume's VSAM data space. You can 
specify a maximum of five volumes for each workfile. See the section 
"How an Alternate Index is Built" for a description of how to calculate the 
amount of space to be suballocated for each sort workfile. If your 
BLDINDEX job requires external-sort workfiles, this space must be 
available on the volume(s) identified by \oher or your job will fail. 

UNIT=Jevr}53e 

Type of direct-access device on which the volume is mounted. You can 
specify a generic device type (that is, 3330, 2314, etc.) or a unit address 
(that is, 121, 248, etc.). You cannot specify SYSDA. 

DISP=OLD 

Required 

AMP=*AMORG' 

Required. 

If BLDINDEX is being used interactively in a TSO environment, these sort 
workfile DD statements must be contained in a logon procedure. 



Order of Catalog Use: BLDINDEX 

The base cluster and alternate-index entries are in the same catalog, because 
the catalog owns the volume or volumes that contains the cluster and its 
alternate index. 

The order in which catalogs are selected to determine the catalog to contain 
the external-sort workfile entries (that is, entries that describe each workfile 
as an entry-sequenced cluster in a suballocated VSAM data space) is: 

1. If a catalog is specified with the CATALOG parameter, that catalog is 
selected to contain workfile entries. Otherwise, 
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2. The user catalog specified in the current job step (STEPCAT) or, if none is 
specified for the job step, the user catalog specified for the current job 
(JOBCAT) is selected to contain the workfile entries. If more than one 
catalog is specified for the job step or job, the first job step or job catalog 
is selected to contain the workfile entries. Otherwise, 

3. If the entries (data set name on the DD statement) are identified with 
qualified entrynames and the first qualifier is the same as: 

- the name of a user catalog, or 

- the alias of a user catalog, 

the user catalog so identified is selected to contain the workfile entries. 
Otherwise, 

4. The master catalog is selected to contain the workfUe entries. 
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MODIFYING CATALOG INFORMATION 



The ALTER command is used to alter attributes in catalog entries and to 
rename members of nonVSAM partitioned data sets. To alter an entry, you 
need to supply its name and the attributes to be altered. 

Altering an entry does not normally require that the entry's volume be 
mounted, because the entry's use of space and the availability of space in the 
volume's data spaces can be determined by examining the catalog. The entry's 
volume must be mounted whenever the volume's VTOC must be consulted or 
modified, such as when a unique component or nonVSAM data set is 
renamed. The entry's volume must also be mounted when the entry is 
cataloged in a recoverable catalog. A JCL DD statement can be used to cause 
the data set or volume to be allocated. In OS/VS2 MVS, a data set or volume 
can be dynamically allocated by specifying the data-set name or volume serial 
number if no DD statement is supplied. The volume must be mounted as 
permanently resident or reserved. 

Key-sequenced VSAM data sets consist of three components: an index 
component, a data component, and the cluster entry itself. Most attributes of 
the VSAM data set are associated with its data or index components. Certain 
attributes such as retention period, owner ID, and cluster protection are 
associated with the cluster entry itself. If you use the cluster name in the 
ALTER command, only these attributes will be changed. If you use the 
cluster name in the ALTER command to alter any attribute not directly 
associated with the cluster entry. Access Method Services will terminate the 
ALTER request and issue an error message. The converse is also true; if you 
specify a data or index component name and attempt to alter an attribute 
directly associated with a cluster entry, Access Method Services will terminate 
your ALTER command and issue an error message. You must specify the 
explicit data or index component name in order to alter any of the remaining 
attributes such as shareoptions, buff erspace, writecheck, the data or index 
protection attributes, etc. It is recommended, therefore, that you specify data 
and index component names at DEFINE time in order to facilitate the use of 
the ALTER command. Otherwise, you wiU have to use the long 
system-generated names. Refer to Figure 8 in the chapter "Command 
Format" to determine which values or attributes you may alter for a particular 
entry tjrpe. 

You cannot ALTER any attributes of a user catalog except those directly 
associated with the cluster name. Data and index component names specified 
for a user catalog at DEFINE tune are meaningless, because the system will 
always generate standard names. If you specify these system-generated names 
for the data or index components in the ALTER command, VSAM will return 
a catalog return code of "8", claiming the entry is not there. Additionally, if 
you alter the expiration date to an invalid date, such as "99999", Access 
Method Services will return a condition code of "0" even though the 
expiration date remains unchanged. 

Refer to the chapter "Command Format" for a description of the command 
format for ALTER, Examples of the ALTER command are also included. 



f 



Modifying Catalog Information 99 



Order of Catalog Use: ALTER 



The order in which catalogs are searched when an entry is to be located to be 
altered is: 

1. If a catalog is specified in the CATALOG parameter, only that catalog is 
searched. If the entry is not found, a "no entry found" error is returned to 
the user. 

2. Any user catalog(s) specified in the current job step (with a STEPCAT DD 
statement) is searched. If more than one catalog is specified for the job 
step, the catalogs are searched in order of concatenation. If the entry is 
found, no other catalog is searched. 

If a STEPCAT catalog is specified and the entry is not found, the 
JOBCAT catalog is not searched. The catalog search continues with step 3 
below. 

If no STEPCAT catalog is specified for the job step, and a user catalog is 
specified for the current job (with a JOBCAT DD statement), the 
JOBCAT catalog(s) is searched. If more than one catalog is specified for 
the job, the catalogs are searched in order of concatenation. If the entry is 
found, no other catalog is searched. Otherwise, 

3. If the entry is identified with a qualified entryname and its fu-st qualifier is 
the same as: 

-- the name of a user catalog, or 

- the alias of a user catalog, or 

- the alias of a control volume, 

the user catalog or control volume so identified is searched. If the entry is 
found, no other catalog is searched. Otherwise, 

4. The master catalog is searched. If the entry is not found, a "no entry 
found" error is returned to the user. 



Generic Names and ALTER 



To alter entries with quaUfied names— for example, 

PAYROLL.74.MAY— you can identify the entr^' with its full nair.e (that is, 
all qualifiers) or with all qualifiers but one. The unspecified qualifier is 
indicated with an asterisk (for example, PAYROTJ_„*MAY). This kind of 
shortened name, PAYROLL.*. MAY, is caUed a generic name. When you 
specify the full entryname, only the entry so identified is modified. When you 
specify all qualifiers of the entryname but one, the entries whose entry names 
match the supplied qualifiers are altered, if they contain the type of 
information specified with the ALTER coromand's parameters. 

For example, when you specify PAYROLL.*, the entries that might be 
altered are those whose entrynames contain two qualifiers, the first qualifier 
being PAYROLL. When you specify PAYROLL.*. MAY, the entries that 
might be altered are those whose entrynames contain three qualifiers, the first 
being PAYROLL and the third and last being MAY. 

When you identify a catalog (that is, when you specify the ALTER 
command's CATALOG parameter), Access Method Services searches only 
the specified catalog for generically named entries. If no catalog is specified, 
the catalog is selected as indicated in "Order of Catalog Use: ALTER" and is 
searched for generic-named entries. 
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You must always specify the first qualifier of a qualified entryname. You can 
substitute an asterisk for no more than one of the other qualifiers. 

You must identify all qualifiers in the qualified name. For example, 
PAYROLL.* cannot be used to identify a qualified name that contains three 
or. more qualifiers, even though its first qualifier is PAYROLL. 
PAYROLL.74.MAY.* cannot be used to identify a qualified name that has 
more or fewer than four qualifiers. 



Renaming GenericaDy-Named Entries 



You can use generic names to rename a group of cataloged objects. To do 
this, you specify both the entryname and the new name as generic names. For 
example, if each entryname identified with the generic name A.*.B is to be 
renamed with the generic name A.*.C, all entrynames that have A as the first 
qualifier and B as the third and last qualifier are renamed. The new name has 
A as the first qualifier and C as the third and last qualifier: 



Old Name 


NewNanie 


A.1.B 


A.1.C 


A.2.B 


A.2.C 


A.3.B 


A.3.C 



If each entryname identified with the generic name A.B.*.D is to be renamed, 
all entrynames that have A and B as the first and second qualifiers, and D as 
the fourth and last qualifier, are renamed. If the new generic name is 
C.*.DATA, the entry names are renamed as follows: 

Old Name New Name 



A.B.1.D 


C.l.DATA 


A.B.2.D 


C.2.DATA 


A.B.3.D 


C.3.DATA 



VSAM Volume Recovery Function 



The VSAM Volume Recovery function removes all VSAM data spaces and 
resets volume ownership for a volume that cannot be located with its catalog 
entry (that is, a system failure or I/O error might have damaged the volume 
entry). The volume's format-4 DSCB (in the VTOC) is reset to remove its 
ownership from the VSAM catalog. NonVSAM data sets on the volume are 
not affected. The VSAM catalog that owns the volume is not accessed or 
modified — ^the (damaged) volume entry is unchanged. 

The VSAM Volume-Recovery function can be used to remove a user catalog 
from a volume without first deleting each of the catalog's objects (that is, 
VSAM objects and nonVSAM data sets described with the catalog's entries). 
The VSAM Volume-Recovery function allows you to remove a VSAM user 
catalog that has been damaged by a head crash, a standalone DASDI, or a 
similar accident. 

VSAM erases all VSAM data spaces (even when they contain data or a 
catalog) and rewrites the volume's VTOC to indicate additional free space on 
the volume. You should use this function only when you cannot access the 
catalog that owns the volume. You should use the function carefully, in order 
to prevent unwanted loss of data. When improperly used, this function can 
contribute to system integrity exposures. See the section "VSAM Volume 
Cleanup" in the chapter "Data Security and Protection" for further 
information about the volume-recovery function. 
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When you use the ALTER command to recover from a damaged volume, you 
code the command in this format: 

ALTER entryname [ / password ] 
FILE( dname ) 
REMOVEVOLUMES( volser [ b vober ... ] ) 

entryname [ / password ] 

names the master catalog. If the master catalog is password protected, then 
its master password must also be supplied. 

FILE( dname ) 

specifies the name of a DD statement that describes a volume to be reset. 
If more than one volume is to be reset, they must be of the same device 
type. Concatenated DD statements are not allowed. This parameter is 
required. 

REMOVEVOLUMESC volser [ b volser ... ] ) 

identifies the volume(s) on which all VSAM data spaces are to be 
removed. VSAM ownership of the volume is also relinquished. Volumes 
owned by the master catalog identified in entryname cannot be specified. 



102 OS/VS2 Access Method Services 



DISPLAYING CATALOG INFORMATION 



The LISTCAT command is used to list entries from a catalog. The entries 
listed can be selected by name or entry type, and the fields to be listed for 
each entry can additionally be selected. See "Appendix B: Interpreting 
LISTCAT Output" for an explanation of the output produced as a result of 
the LISTCAT command. 

If entries to be listed are selected by name, the name(s) can be specified in its 
entirety, can be specified as a generic name, or can be specified with the 
LEVEL parameter. 

Entries are specified by generic name by supplying all but one qualifier of the 
name. The qualifier omitted is indicated by an asterisk (*). The first qualifier 
cannot be omitted. 

When you specify ENTRIES (A.*), all two-qualifier entry names that have A 
for the first qualifier are selected to be listed. When you specify 
ENTRIES(A.*.B), all three-qualifier entrynames that have A as the first 
qualifier and B as the last qualifier are selected to be listed. You can further 
limit the printing by identifying certain entry types to be printed (that is, by 
specifying NONVSAM, CLUSTER, etc.). 

When you specify LEVEL(A.*.B), all entrynames that have A as the first 
qualifier and B as the third qualifier are selected to be listed — and some of the 
selected entrynames might have four or more qualifiers (each must have at 
least three qualifiers and satisfy the A.*.B selection criteria). 

When you specify LEVEL(A), all entrynames that have A as the first 
qualifier (regardless of the number of qualifiers) are selected to be listed. 

You cannot specify an "*" as the last qualifier when you use the LEVEL 
parameter (note that when you specify LEVEL(A), more entries might be 
listed than when you specify ENTRIES(A.*), even though both ways appear, 
at first glance, to be identical). If you specify LEVEL(A.*), the LISTCAT 
operation terminates with an error message. 

Refer to the chapter "Command Format" for a description of the command 
format for LISTCAT. Examples are also included. 



Order of Catalog Use: LISTCAT 



When the ENTRIES or LEVEL parameter is not specified, or when the 
command is not executed through TSO, the order in which catalogs are 
searched when entries are to be listed using the LISTCAT command is: 

L If a catalog is specified in the CATALOG parameter, only that catalog is 
listed. Otherwise, 

2. The first user catalog specified in the current job step (STEPCAT) or, if 
none is specified, the first user catalog specified in the current job 
(JOBCAT) is listed. Otherwise, 

3. If no user catalog is specified in the current job step or job, the master 
catalog is listed. 
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When the ENTRIES or LEVEL parameter is specified, or when the command 
is executed through TSO, the order in which catalogs are searched when 
entries are to be listed using the LISTCAT command is: 

1. If a catalog is specified in the CATALOG parameter, only that catalog is 
searched. If the entry is not found, a "no entry found" error is returned to 
the user. Otherwise, 

2. Any user catalog(s) specified in the current job step (STEPCAT) or, if 
none is specified for the job step, any user catalog(s) specified for the 
current job (JOBCAT). If more than one catalog is specified for the job 
step or job, the job step or job catalogs are searched in order of 
concatenation. If the entry is found, no other catalog is searched. 
Otherwise, 

3. If the entry is not found, and the entry's name is a qualified name, and the 
first qualifier (that is, the first one to eight characters before a period) is 
the same as: 

- the name of a user catalog, or 

- the alias of a user catalog, or 

- the alias of a control volume, 

that user catalog or control volume is searched. If the entry is found, no 
other catalog is searched. Otherwise, 

4. The master catalog is searched. If the entry is not found, a "no entry 
found" error is returned to the user. 
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DELETING CATALOG ENTRIES 

The DELETE command is used to delete entries from a catalog or to delete 
members of a nonVSAM partitioned data set. When the entry represents an 
object that contains space in a VSAM data space, the object's space is made 
available for other VSAM objects. 

Deleting an entry does not normally require that the entry's volume be 
mounted, because the entry's use of space in the volume's data spaces can be 
determined by examining the catalog. The entry's volume must be mounted 
whenever the volume's VTOC must be consulted or modified, such as when: 

• A data space, a unique component, or a user catalog is to be deleted. 

• A cluster or alternate index is to be deleted and erased. 

• A nonVSAM data set is to be deleted and scratched. 

If the entry is cataloged in a recoverable catalog, its prime catalog recovery 
area volume must be mounted so that the CRA can be updated to reflect the 
entry's deletion. 

For multivolume VSAM data sets, each volume must be mounted to reflect 
the entry's deletion from the volume's catalog entry. See "Restoring Catalog 
Entries After System Failure" for a description of catalog recovery area 
contents. 

JCL can be used to cause a data set or volume to be allocated. A data set or 
volume can be dynamically allocated by specifying the data set name or 
volume serial number if no DD statement is supplied. Any volume to be 

dynamically allocated must be mounted as permanently resident or reserved. 

\ 

J Entries can be deleted from more than one catalog with a single DELETE 

conmiand. You do this by specifying many entry names and not coding the 
CATALOG parameter. Use concatenated JOBCAT or STEPCAT DD 
statements to identify the catalogs that contain the entries. 

Note: When two catalogs in your system might contain the same entryname, 
you should issue separate DELETE commands that reference each catalog. 

The kinds of catalog entries you can delete are: 

• ALIAS — ^The alias entry is deleted. 

You can delete the alias of a user catalog and redefine it in the same 
step, but you cannot use it in that step. A TSO session is considered one 
step so you would have to log off and log on to use an alias of a user 
catalog that you had deleted and redefined. 

Password required: the catalog's update- (or higher-level) password. 

• ALTERNATEINDEX— The alternate-index entry, its data component's 
entry, and its index component's entry are deleted. Space allocated to the 
alternate index's components is made available for other VSAM objects. 
Each path entry that relates the alternate index to its base cluster is also 
deleted. 

When ERASE is coded, or when the alternate index has the ERASE 
attribute, the volume containing the alternate index's data component 
must be mounted. 
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The alternate index's components cannot be deleted separately. You 
must delete the alternate index as a whole. When the alternate index's 
components reside in unique data spaces, the volumes containing these 
components must be mounted. 

If the alternate index is cataloged in a recoverable catalog, the prime 
catalog recovery area volume as well as other volumes for the alternate 
index must be mounted. The prime volume is the first index volume of 
the base cluster over which the alternate index is defined if the cluster is 
a KSDS. Otherwise, it is the data volume of the cluster. Its volume serial 
number is printed by Access Method Services when the alternate index 
is defined. 

Password required: the alternate index's master password or its catalog's 
master password. 

• CLUSTER — The cluster entry, its data component's entry, and, if the 
cluster is key-sequenced, its index component's entry are deleted. Space 
allocated to the cluster's components is made available to other VSAM 
components. 

Alternate indexes that are associated with the cluster are deleted. The 
cluster's upgrade-set entry, if it exists, is also deleted. Path entries that 
relate the cluster to its alternate indexes are also deleted, as weU as path 
entries that have been defined for the cluster alone. 

Space allocated to the alternate index's components is made available to 
other VSAM objects. When the alternate index's components reside in 
unique data spaces, the volumes containing these components must be 
mounted. 

When ERASE is coded, or when the cluster has the ERASE attribute, 
the volume containing the cluster's data component must be mounted. 

The cluster's components cannot be deleted separately. You must delete 
the cluster as a whole. When the cluster's components reside in unique 
data spaces, the volumes containing these components must be 
mounted. 

When the cluster is cataloged in a recoverable catalog, the prime catalog 
recovery area of the volume as weU as all other volumes of the cluster 
luusi be mounted. The pnme volume is the first volume containing the 
index component of the cluster if the cluster is a KSDS. Otherwise, it is 
the first data volume of the cluster. Its volume serial number is printed 
by Access Method Services when the cluster is defined. 

Password required: the cluster's master password or its catalog's master 
password. 

• GENERATIONDATAGROUP — The generation data group entry is 
deleted. The generation data group must be empty (that is, it cannot 
contain generation data sets) unless you specify FORCE. 

Password required: the catalog's update- (or higher-level) password. 

• MASTERCATALOG — In a VS2 system, the VSAM master catalog is the 
system's primary catalog. You are not allowed to delete your system's 
master catalog. 
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• NONVSAM— The nonVSAM entry is deleted. When SCRATCH is coded, 
the data-set's DSCB is removed from its volume's VTOC — the volume 
containing the nonVSAM data set must be mounted. 

All alias entries that point to the nonVSAM entry are also deleted. 

When the nonVSAM data set is partitioned, you can delete one of its 
members by specifying the entryname as 
pdsname(membername) 

Password requu-ed: the catalog's update- (or higher-level) password. 

• PAGESPACE — ^The page-space entry and its data-component entry are 
deleted. Space allocated to the page-space is made available to other 
VSAM objects. 

The page space being deleted must be inactive when it is deleted, and all 
other page spaces on the same volume must also be inactive. 

Password required: The page space's master password or the catalog's 
master password. 

• PATH — ^The path entry is deleted. Entries for the path's alternate index 
and base cluster are undisturbed. 

Password required: The path's master password or its catalog's master 
password. 

• SPACE — All empty data spaces on the volume are deleted. The DSCB 
entry that describes each deleted VSAM data space in the volume's VTOC 
is removed. The space is made available to other OS/VS2 system objects. 

When all VSAM data spaces on the volume have been deleted, or when 
you specify FORCE, its volume entry in the catalog is deleted. The 
volume ownership indicator in the volume's VTOC is reset so that a 
VSAM catalog no longer owns the volume. 

When the last data space on a volume is deleted and the volume is not a 
candidate volume, the volume's entry is also deleted from the catalog. 
The effect of deleting the volume entry is that the volume is no longer 
owned by the catalog, that is, another catalog is free to allocate space on 
the volume. 

The volume must be mounted. 

You cannot specify the PURGE parameter when you delete VSAM data 
spaces. 

When you identify data spaces to be deleted, you cannot identify any 
other type of cataloged object to be deleted with the same command. 
You can, however, follow the DELETE SPACE command with other 
Access Method Services commands. 

Password required: the catalog's update (or higher-level) password. 
When you also specify FORCE, you must supply the catalog's master 
password. 
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• USERCATALOG — ^The catalog's self-describing entries and its 

user-catalog entry in the master catalog are deleted. The DSCB entry that 
describes the user-catalog's data space is removed from the volume's 
VTOC. The volume-ownership indicator in the volume's VTOC is reset so 
that the volume is not owned by a VSAM catalog. 

The catalog must be empty — it cannot contain any catalog entries, 
unless you specify FORCE. 

All alias entries in the master catalog that point to the user-catalog 
connector entry are also deleted. 

You cannot code the ERASE or CATALOG parameters when you 
delete a user catalog. 

The catalog's volume must be mounted. If the volume is unavailable or 
inaccessible, DELETE cannot be used. You should use EXPORT 
DISCONNECT instead. 

You can delete a user catalog and redefine it in the same step, but you 
cannot use the redefined catalog in that same step. A TSO session is 
considered one step so you would have to log off and then log on to use 
a catalog that you have deleted and redefined. 

If there is any possibility of other users accessing a user catalog whOe it 
is being deleted, you should serialize the job or job step that deletes the 
catalog by providing a JOBCAT or STEPCAT DD statement specifying 
the catalog name as dsname and DISP=OLD. 

Password required: the user catalog's master password is specified with 
its entryname. 

You cannot delete a data or index entry separately from its associated cluster, 
alternate index, or user catalog entry. 

If the only object on a VSAM volume is a cluster or alternate index that 
resides in a unique data space, deleting its entry does not cause VSAM 
volume ownership to be relinquished. The volume entry remains in the catalog 
in a candidate status. You must issue a DELETE SPACE command to cause 
VSAM to release ownership of the volume. 

Refer to the chapter "Command Format" for a description of the command 
lonnai for DELETE. Examples of deleting VSAM and nonVSAM data sets 
are also included. 



Order of Catalog Use: DELETE 



The order in which catalogs are searched when an entry is to be located to be 
deleted is: 

1. If a catalog is specified in the CATALOG parameter, only that catalog is 
searched. If the entry is not found, a "no entry found" error is returned to 
the user. 

2. Any user catalog(s) specified in the current job step (with a STEPCAT DD 
statement) is searched. If more than one catalog is specified for the job 
step, the catalogs are searched in order of concatenation. If the entry is 
found, no other catalog is searched. 

If a STEPCAT catalog is specified and the entry is not found, the 
JOBCAT catalog is not searched. The catalog search continues with step 3 
below. 
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If no STEPCAT catalog is specified for the job step, and a user catalog is 
specified for the current job (with a JOBCAT DD statement), the 
JOBCAT catalogCs^is searched. If more than one catalog is specified for 
the job, the catalogs are searched in order of concatenation. If the entry is 
found, no other catalog is searched. Otherwise, 

3. If the entry is identified with a qualified entryname and its first qualifier is 
the same as: 

- the name of a user catalog, or 

- the alias of a user catalog, or 

- the alias of a control volume, 

the user catalog or control volume so identified is searched. If the entry is 
found, no other catalog is searched. Otherwise, 

4. If the entry is not found, the master catalog is searched. If the entry is not 
found in the master catalog, a "no entry found" error is returned to the 
user. 



Generic Names and DELETE 



To delete entries with qualified names — ^for example, 
PAYROLL.74.MAY — you can identify the entry with its full name (that is, 
all qualifiers) or with all qualifiers except one. The unspecified qualifier is 
indicated with an asterisk (for example, PAYROLL.*. MAY). This kind of 
shortened name, PAYROLL.*. MAY, is called a generic name. When you 
specify the full entryname, only the entry so identified is modified. When you 
specify all qualifiers of the entryname except one, the entries whose 
entrynames match the supplied qualifiers are deleted, if they satisfy other 
parameters specified with the DELETE command's parameters. 

For example, when you specify PAYROLL.*, the entries that might be 
deleted are those whose entrynames contain two qualifiers, the first qualifier 
being PAYROLL. When you specify PAYROLL.*. MAY, the entries that 
might be deleted are those whose entrynames contain three qualifiers, the first 
being PAYROLL and the third and last being MAY. 

When you identify a catalog (that is, when you specify the DELETE 
command's CATALOG parameter). Access Method Services searches only 
the specified catalog for generically named entries. If no catalog is specified, 
the catalog is selected as indicated in "Order of Catalog Use: DELETE" and 
is searched for generic-named entries. 

You must always specify the first qualifier of a qualified entryname. You can 
substitute an asterisk for no more than one of the other qualifiers. 

You must identify all qualifiers in the qualified name. For example, 
PAYROLL.* cannot identify a qualified name that contains three or more 
qualifiers, even though its first qualifier is PAYROLL. PAYROLL.74.MAY.* 
cannot identify a qualified name that has more or fewer than four qualifiers. 
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MOVING ENTRIES 



The EXPORT and DVIPORT commands allow you to create backup copies of 
alternate indexes and clusters, to transport user catalogs, alternate indexes 
and clusters from on(i system to another, and to prevent (and subsequently, 
with the IMPORT cc>mmand, to allow) usage of a user catalog. 

When a user catalog is exported, its catalog-connector entry is removed from 
the master catalog. When the user catalog is subsequently imported to a new 
system, a catalog-connector entry is created for it in the new system's master 
catalog and the user catalog is physically transported to the new system. The 
user-catalog volume itself need not be mounted either to export or import the 
user catalog. When a user catalog is exported, it is not copied; the user catalog 
remains on its volume in its original form. The user catalog and its cataloged 
objects are unavailable to any user until the user catalog is connected (with 
the IMPORT CONNECT command) to a master catalog. 

You do not have to issue the EXPORT command to allow a user catalog to be 
moved to another system. If the catalog is on a demountable volume, you can 
physically move the volume to another system. You must use an IMPORT 
CONNECT command to build a catalog-connector entry for the user catalog 
in the new system's master catalog. When you issue the EXPORT 
DISCONNECT command, VSAM removes the user-catalog's connector 
entry. 

Note: If you issued the EXPORT DISCONNECT conunand and your user 
catalog is protected by the RACE Program Product, the RACE profile will 
not be automatically deleted. It is your responsibility to remove the profile 
with RACE utility DELDSD. For more information, see the publication 
OS/VS2 Resource Access Control Facility (RACE) Command Language 
Reference. 

When a cluster or alternate index is exported, its catalog entry is copied to a 
movable volume along with the object's contents. The entries and 
components are subsequently copied into a new system. 

Exportation of a cluster or alternate index is either permanent or temporary. 
In permanent exportation, the catalog record is deleted and storage space is 
freed in the original system. In temporary exportation, both the sending and 
receiving systems retain a copy of the object, but the copy in the original 
system is marked to indicate that there is a copy elsewhere. If you want to 
export permanently a base cluster and its associated alternate indexes, the 
alternate indexes must be exported first since deletion of a base cluster causes 
deletion of any alternate indexes defined over it. A base cluster must always 
be imported prior to importing any of its alternate indexes. 

When a cluster or alternate index is exported, its catalog information (that is, 
the attributes specified with the DEFINE command— except the catalog's 
name — and modified with subsequent ALTER commands) is moved with the 
cluster's data records. However, the statistics kept in the catalog entry are lost 
(that is, the statistics are not available when the entry is subsequently 
imported). After the import the statistics stored in the catalog entry are the 
results of the import only. You cannot export an empty cluster or alternate 
index. 

The permanent exportation of a RACF-protected cluster or alternate index 
causes the deletion of the data-set profiles. A temporary exportation does not. 
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Also, when a RACF-protected data set is exported, the RACF indicators are 
moved to the portable data set, but the profile is not. 

When a previously exported RACF-protected object is imported, you have an 
option to reuse the old profiles or to establish new ones. The IMPORT 
command in the chapter "Command Format" will give you more information 
on RACF options when importing a VSAM object. 

Exporting or importing a RACF-protected catalog will cause no change in the 
status of the RACF indicators in the catalog or the profiles associated with 
the catalog. 

The portable copy of a cluster or alternate index is a variable-blocked, 
spanned, sequential data set. Each record of a relative-record data set 
contains an 8-byte header. Each record of all other types of VSAM data sets 
contains a 4-byte header. The maximum logical record length of the portable 
data set is based on the maximum record size of the VSAM data set to be 
exported. Access Method Services uses the value you specified via the 
maximum subparameter of the RECORDSIZE parameter of the DEFINE 
CLUSTER or ALTERNATEINDEX command when the data set was 
defined. The resulting maximum logical record length of the portable data set 
is as specified below: 

• For relative-record data sets, the greater of 276, or VSAM maximum 
record size + 8 

• For all other types of VSAM data sets, the greater of 272, or VSAM 
maximum record size + 4 

The resulting maximum logical record length of the portable data set is limited 
to 32,760 bytes (Access Method Services does not support the DCB 
parameter, LRECL=X). Therefore, the largest VSAM maximum record size 
which can be handled by EXPORT is: 

• 32,752 for relative-record data sets 

• 32,756 for all other types of VSAM data sets 

If the data set to be exported has been defined with a maximum record size 
greater than the appropriate length shown above, the EXPORT command 
terminates with an error message. 

You may specify, vvith tlic DCB parameter of the uD statement for the 
portable data set, a blocksize other than the default of 2048 bytes. 

Refer to the chapter "Command Format" for a description of the command 
formats for the EXPORT and IMPORT commands. Examples showing how 
data sets are exported and imported are also included. 
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Exporting an Entry 



Importing an Entry 



The EXPORT command is used in conjunction with the IMPORT command 
to move alternate indexes, clusters, and user catalogs from one system to 
another, to provide backup copies of clusters and alternate indexes, and to 
sever the relationship between a user catalog and the master catalog. The 
EXPORT command cannot be used to move or provide a backup copy of a 
master catalog, a nonVSAM data set, data space, generation data group, page 
space, or path. Access Method Services automatically exports along with a 
cluster or alternate index any paths defined over it. The paths are redefined 
when the object is subsequently imported. 

If a user catalog is to be exported, the catalog is merely disconnected from the 
master catalog. The user catalog can then be physically (or logically) moved 
to another system. Even if the catalog is not moved to another system, it is 
temporarily unavailable to all users, and its aliases are deleted. The person 
who is responsible for the catalog can issue IMPORT CONNECT to make 
the catalog available again. 

You should take care to list the user-catalog's aliases before you issue the 
EXPORT command. You can use the LISTCAT command to list the aliases: 

LISTCAT - 

CATALGGC mastercatname fpassword )- 

ENTRIES( usercatnameh 

ALL 

The user-catalog's aliases are listed under the heading "ASSOCIATIONS." 

When you use the IMPORT command to make the catalog available to 
another system, you can issue the DEFINE ALIAS command to reestablish 
each of the catalog's aliases. 

When a VSAM cluster or alternate index that has paths dr 'In J over it is 
exported, the catalog information for those paths is also exported. IMPO^ 
uses this information to reestablish the paths in the target catalog. Therefi 
EXPORT can be used to export path entries, but only as parts of a larger 
structure being exported (that is, a cluster or alternate index). 



The IMPORT command is used in conjunction with the EXPORT command 
to move a cluster, alternate index, or user catalog from one system to anothei 
When a cluster or alternate index is imported, it is automatically reorganized. 
When you move an object into the new system, you can change some of its 
attributes (as described with the OBJECTS subparameters). 

When a user catalog is moved into a system, you may connect it to the master 
catalog in the new system, thereby making the user catalog available in the 
new system. The user catalog might have been disconnected to make it 
temporarily unavailable to users even though its volume is not moved. The 
person who is responsible for the catalog can issue IMPORT CONNECT to 
make it available again. 
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A cluster, alternate index, or user catalog cannot be moved into a system if its 
name or the names of any of its components is the same as any name that 
already exists in the receiving catalog. There are two exceptions to this: 

• When IMPORT is used to replace a cluster or alternate index with its 
backup copy. When the object's backup copy was made, its catalog entry 
was marked temporary (that is, TEMPORARY was coded when the object 
was exported). The object's temporary entry is deleted when it is imported; 
a new entry is built and imported in place of the temporary entry. 

• When the cluster or alternate index has been predefined in the receiving 
catalog. The predefined entry must be for an empty data set. If a duplicate 
entryname exists for an empty data set, IMPORT assumes that this is a 
predefined entry whose attributes and space allocation are to be used in 
place of those in effect when the data set was exported. 

If duplicate entrynames are found and the entry in the receiving catalog is not 
marked as temporary and is not empty, the IMPORT command is terminated. 

The first record of the copy to be imported causes an entry to be defined in 
the receiving system. A check is made for a duplicate name; if a duplicate 
name exists and is marked temporary, the duplicated name is deleted from the 
receiving system so that the new entry can be defined. The deletion takes 
place even if the request for import cannot subsequently be completed. 

A check is also made for an empty target data set. If such a data set is 
present, IMPORT makes no attempt to define a replacement data set. 
Instead, IMPORT copies the data records from the portable data set into the 
empty target data set. If you wish to import into an empty target data set, you 
must specify the INTOEMPTY parameter. 
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CONVERTING AN OS CATALOG'S ENTMES TO 
VSAM CATALOG ENTRIES 



When you want to use the entries in an OS catalog with your VS2 system, you 
can either establish a connector in the master catalog to the OS catalog or you 
can convert the OS catalog entries to VSAM catalog entries. (Note: The OS 
catalog is called a control volume or CVOL.) You can convert the OS CVOL 
entries to VSAM catalog entries using one of two methods: 

• Use the DEFINE command to convert some of the entries in an OS CVOL 
to VSAM catalog entries. 

• Use the CNVTCAT command to convert all of the entries in an OS CVOL 
to VSAM catalog entries in a user or master catalog. 

Refer to chapter "Command Format" for a description of the command 
format for CNVTCAT. Examples are also included. 

Connecting an OS CVOL to the Master Catalog 

When you want to use an OS CVOL in an OS/VS2 system, you must define 
the CVOL in the system's master catalog. For a description of how this is 
done, and how OS CVOLs are used in an OS/VS2 system, see OS/VS2 
Using OS Catalog Management with the Master Catalog: CVOL Processor. 

Using the DEFINE Command to Convert Some of the CVOUs 
Entries 

When you issue the DEFINE command to redefine, in a VSAM catalog, 
objects cataloged in an OS catalog (that is, OS CVOL), you can: 

• Selectively catalog entries from the OS catalog 

• Convert a large OS catalog to two or more VSAM catalogs, without first 
splitting the OS catalog 

However, this method requires that you issue (that is, keypunch or type in) 
many DEFINE commands. To lessen the amount of keypunching, you might 
use the following procedure: 

1. Execute the lEHLIST utility program to list the OS catalog. The output of 
the program is the input to step 2. The lEHLIST program is described in 
detaUin 0S/VS2 MVS Utilities. 

2. Write and execute: 

• A program to generate DEFINE ALIAS statements for each CVOL 
pointer entry and alias entry in the OS CVOL listing. 

• A program to generate DEFINE ALIAS statements for each CVOL 
pointer entry that relates the CVOL pointer names to the appropriate 
catalog name. 

• A program to generate DEFINE NONVSAM statements for each 
nonVSAM data set in the OS CVOL listing. 

. A program to generate DEFINE GENERATIONDATAGROUP 
statements for each generation-index pointer entry in the OS CVOL 
listing. 
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The output of step 1 (the lEHLIST listing) is the input to your program. 
The output of your program is a series of DEFINE ALIAS, DEFINE 
NONVSAM, and DEFINE GENERATIONDATAGROUP commands. 

3. Select the DEFINE statements that represent the entries you want 
cataloged in one of the VSAM catalogs. 

4. Code and execute the appropriate JCL statements to execute the Access 
Method Services program, IDCAMS, using the selected DEFINE 
statements from step 3 as SYSIN input statements. 

5. Repeat steps 3 and 4 until you have selected and cataloged as many entries 
as you Want in the appropriate VSAM catalogs. CVOL aliases must be put 
in the VSAM master catalog. 



Using the CNVTCAT Command to Convert All of the OS CVOL's 
Entries to VSAM Catalog Entries 



The CNVTCAT command is used to convert entries in an OS catalog to 
entries in an existing master or user catalog. CNVTCAT converts data-set 
entries, generation data group entries, alias entries, and CVOL-pointer entries 
to appropriate VSAM catalog entries. 

CNVTCAT was designed to be executed only once for an OS catalog. The 
execution of CNVTCAT is time-consuming for any catalog greater than one 
hundred entries. Therefore, you should not plan to repeatedly convert the 
entries of a large OS catalog. 

When an OS catalog structure of a system catalog and many OS CVOLs are 
converted to a VSAM master catalog and many user catalogs, you can use 
Access Method Services commands to perform the entire operation. You can 
also merge an OS CVOL's entries into a VSAM catalog, using the 
CNVTCAT command. However, you cannot easily divide the entries of a 
large OS catalog among many VSAM user catalogs. When the OS catalog is 
organized on the basis of qualified data-set names, you can split the OS 
catalog into two or more OS catalogs using the lEHMOVE function of a 
selective COPY CATALOG command. You can then convert the entries of 
the smaller OS catalogs into selected VSAM catalogs. When the OS catalog is 
not organized by qualified data set name, you can catalog each individual 
entry using the DEFINE command as illustrated in the section "Using the 
DEFINE Command to Convert Some of the CVOL's Entries." 

OS control volumes (CVOLs) can be interchanged within different operating 
systems: OS, VS2-1, VS2-2, and VS2-3. When you intend to continue 
production on another operating system while converting to OS/VS2, you 
might want to use OS CVOLs because they can be transferred between 
operating systems. 

When you catalog an OS CVOL in the system's master catalog, you can use 
the CVOL to point to its cataloged entries. You cannot use a STEPCAT or 
JOBCAT DD statement to identify an OS CVOL, however; an OS CVOL 
and a VSAM user catalog might reside on the same volume, since the CVOL 
is considered a nonVSAM data set. 

You can issue the DELETE ALIAS command to delete a CVOL's aUas in the 
master catalog. When you issue the DELETE NONVSAM command to 
uncatalog the OS CVOL, all of its aliases are also deleted. 

Figure 4 shows OS catalog-entry types, abbreviations, descriptions, and the 
VSAM entry types into which OS catalog entries are converted. 
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Entry Name 


Abbreviation 


Description 


VSAM Entry Type 


Alias entry 


AE 


Contains an 
alternate name for 
the high-level 
qualifier of the 
data set name 


Alias entry. 


Control volume 


CVPE 


Connects another 


Alias entry for a user 


pointer entry 




control volume 


catalog in master 






(CVOL) to this 


catalog. 






CVOL 




Data-set entry 


DSPE 


Contains the name 


NonVSAM entry. 


pointer 




and location of a 
data set 




Generation 


GIPE 


Points to the 


Generation data group. 


index pointer 




lowest index for a 




entry 




generation data 
group 




Generation data 


GOOOOVOO 


Points to a 


NonVSAM entry that is 


set 




generation data set 


attached to a generation 
data group. 


Figure 4. OS Catalog Entry Types 


and VSAM Equivalents 





When you use the CNVTCAT command, you can cause all the entry types 
shown in Figure 4 to be converted or all but the control-volume-pointer 
entries (CVPEs) to be converted. CVPEs are converted to alias entries in the 
master catalog. If, for example, ABC was the name of a control volume 
(CVOL) that resided on volume 123456, ABC becomes the alias in the 
master catalog; you provide the name of the VSAM catalog for which ABC is 
an alias. 

Because CNVTCAT creates aliases for CVPEs, converted OS catalog entries 
can be found without a STEPCAT or JOBCAT DD statement that identifies 
the VSAM catalog to be searched. If, for example, ABC.DEF, which was 
previously contained in an OS catalog, is to be found: 

1. Master catalog is searched because no STEPCAT or JOBCAT is specified. 

2. ABC is found in the master catalog; it is an alias that is related to a 
user-catalog entry. 

3. User-catalog entry points to the user catalog. 

4. ABC.DEF is found as a nonVSAM entry on the user catalog. 

Figure 5 shows an OS catalog, SYSCTLG that contains two CVPEs and 
shows the CVOLs that they point to. Before you can convert the CVPEs, you 
must be able to provide their volume serial numbers. To learn the volume 
serial numbers, list the OS catalog to be converted. If SYSCTLG, shown in 
the top half of Figure 5 is converted, aliases, SYSA and SYSB are created in 
the master catalog. In a separate conversion, the data sets cataloged in SYSA 
and SYSB are converted into entries in existing VSAM catalogs. The bottom 
half of Figure 5 shows the master catalog and two user catalogs after 
SYSCTLG and SYSA and SYSB have been converted. 

The amount of space required in the VSAM catalog depends upon the 
number and kind of records converted. Each OS catalog entry converts to a 
nonVSAM entry in a VS catalog. The exception is alias entries. One alias 
entry in an OS catalog can apply to many data-set names. When the alias is 
converted, one alias entry is created in the VSAM catalog for each data set 
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SYSCTLG 




VSAM Master Catalog 




Figure 5. Converting Control Volume Entries 



that has the high-level qualifier to which the alias appUes. For example, an 
alias, FAKE, exists for REAL. If REAL. A, REAL.B, and REAL.C are 
converted, a total of six records are required in the VSAM catalog: one record 
is requu-ed for each of the three data sets and one record is required for each 
of three aliases, one per data set. See "Estimating the Catalog's Space 
Requirements" to help you estimate the VSAM catalog's size. 

Note: Control volumes can be used in a VS2 system without converting 
entries. See 0S/VS2 Using OS Catalog Management with the Master 
Catalog: CVOL Processor for information about the use of control volumes 
in a VS2 system. 
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Order of Catalog Use: CNVTCAT 



The order in which VSAM catalogs are evaluated to select the catalog that 
receives the converted entries is: 

• If a catalog is specified in the CATALOG parameter, that catalog receives 
the converted entries. Otherwise, 

• The user catalog specified for the current job step (STEPCAT) or, if none 
is specified for the job step, the user catalog specified for the current job 

. (JOBCAT) receives the converted entries. (If more than one catalog is 
specified for the job step or job, the first catalog in order of concatenation 
is selected.) Otherwise, 

• The master catalog receives the converted entries. 

The master catalog always receives alias entries that point to user catalogs. 
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RESTORING A CLUSTER'S END-OF-FDLE VALUES 



When a data set is closed, its end-of-file (EOD) and end-of -key-range 
(EOKR) infonnation is used to upgrade EOD and EOKR information in the 
data set's cataloged information. If an OS/VS system failure occurs before 
the data set is closed (that is, before the user's program issues CLOSE or 
CLOSE(TYPE=T)), the data set's cataloged information is not upgraded. 
This means that the data set's cataloged information contains possibly 
obsolete EOD and EOKR information. The data set's real EOD and EOKR 
indicators are written in the data set, but are not shown in the data set's 
cataloged information. When the data set is subsequently opened and the 
user's program attempts to process records EOD or EOKR, a "no record 
found" error results on a read operation, and a write operation might write 
records over previously written records. 

The VERIFY command is used to compare the end-of -data-set and 
end-of -key range information as it is stored in a VSAM catalog with the true 
end-of-file and end-of -key range. If the information in the catalog does not 
agree with the true end-of-file or end-of -key range, the catalog information is 
corrected. The VERIFY command can be used following a system failure that 
caused a component opened for update processing to be improperly closed. 
Clusters, alternate indexes, and catalogs can be verified. Paths over an 
alternate index cannot be verified. Paths defined directly over a base cluster 
can be verified. Although the data and index components of a key-sequenced 
cluster or alternate index can be verified, the timestamps of the two 
components will be different following the separate verifies, possibly causing 
further OPEN errors. Therefore, you should use the cluster or alternate index 
name as the target of your VERIFY command. 

To use the VERIFY command to verify a catalog. Access Method Services 
must be authorized. See "Authorized Program Facility (APF)" in OS/VS2 
System Programming Library: Supervisor for information about program 
authorization. 

Refer to the chapter "Command Format" for a description of the command 
format for the VERIFY command. 
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RESTORING CATALOG ENTRIES AFTER SYSTEM 
FAILURE 



When you create a user catalog or a master catalog, you can define it as 
recoverable. A recoverable catalog has, on each volume it owns, an area that 
contains a copy of some of the catalog's entries. Each volume's area is called 
the catalog recovery area or CRA. When a system or device failure occurs 
that damages the catalog or some of its entries, each volume's catalog 
recovery area contains the information needed to restore the damaged entries. 
The contents of a volume's catalog recovery area depend on the types of 
objects the volume contains. Figure 6 identifies the volume whose catalog 
recovery area contains a copy of the cataloged object. 



Type of entry 



Vohinie whose catalog recovery area contains a 
copy of the catalog entry 



Volume entry 

Key-sequenced cluster entry and its data 
and index entries 

Alternate-index entry and its data and 
index entries, when the alternate index is 
for a key-sequenced cluster 

Path entry, when the path is related to a 
key-sequenced cluster 

Entry-sequenced cluster's entry and its 
data entry 

Alternate-index entry and its data and 
index entries, when the alternate index is 
for an entry-sequenced cluster 



Its own volume 

The volume that contains the (first part of 
the) cluster's index component 

The volume that contains the (first part of 
the) alternate index's base icluster's index 
component 

The volume that contains the (first part of 
the) path's base cluster's index component 

The volume that contains the (first part of 
the) cluster's data component 

The volume that contains the (first part of 
the) alternate index's base cluster's data 
component 



Path entry, when the path is related to an The volume that contains the (first part of 



entry-sequenced cluster 

Relative-record cluster entry and its data 
entry 

NonVSAM data set 



Generation Data Group 
Alias Entry 



the) path's base cluster's data component 

The volume that contains the (first part of 
the) cluster's data component 

The volume that contains the nonVSAM 
entry's catalog 

The volume that contains the entry's catalog 

The volume that contains the catalog in which 
the nonVSAM association for the alias is 
defined 



User-catalog connector entry in the master The volume that contains the master catalog 
catalog 

Catalog's self-describing entries These entries are not duplicated in any 

catalog recovery area 

Figure 6. Catalog Recovery Area Contents 
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If you should discover that your recoverable catalog is damaged such that its 
entries are inaccessible, are downlevel, or contain erroneous information, you 
have the option of choosing one of two different methods to restore your 
catalog to a usable condition. 

. The EXPORTRA/IMPORTRA Method: You would most likely use this 
method to selectively repair specific catalog entries. Also, remember that 
reorganization of your catalog and your data is a b3Tproduct of this 
approach since it involves the movement of data. You may use the 
following procedure to restore the usability of your catalog. 

1 . Issue the LISTCRA command to list and, optionally, compare the 
catalog recovery area entries (that is, the catalog recovery area that 
contains copies of the damaged catalog entries), 

2. Issue the EXPORTRA command to obtain a copy of the damaged 
entries from the catalog recovery area and, when a VSAM data set entry 
is moved, obtain a copy of the data set's contents. 

3. Clear the damaged volume or reset it so that it is usable by doing one or 
more of the foUowing: 

- Issue the DELETE SPACE command with the FORCE parameter to 
remove VSAM data spaces from the volume. 

- Execute the lEHDASDR program with the DUMP and RESTORE 
statements to restore nonVSAM data sets on the volume. (See 
OS/VS2 MVS Utilities for details.) 

- Execute the lEHDASDR program with the ANALYZE statement to 
initialize the volume. (See 0S/VS2 MVS Utilities for details.) 

- Issue the ALTER REMOVEVOLUMES command to remove the 
VSAM catalog's ownership of the volume. 

4. Issue the IMPORTRA command to reload the data copied and moved 
during step 2 above. 

• The RESETCAT Method: If you do not want your data to be moved and 
if you wish to confine all updating to the catalog (and CRAs), you should 
consider this approach. RESETCAT does not permit selective reset of 
specific catalog entries. An entire volume's worth of catalog entries are 
reset. You would use RESETCAT if a calalog or one or more of its owned 
volumes become inaccessible. Restore the volume(s) from a backup copy 
and issue RESETCA^T to provide the necessary consistency between the 
catalog and the restored volume(s). 

The LISTCRA, EXPORTRA, IMPORTRA, and RESETCAT commands are 
described in detail in the sections that follow. 
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If your catalog was created with the RECOVERABLE option, you can 
determine the damage (if any occurred) that was done to your catalog when a 
system or hardware failure occurred. You can also determine if a volume or 
volumes owned by your catalog is out-of -synchronization with the catalog 
itself (caused, for example, by restoring a volume from a downlevel backup). 
This is because a recoverable catalog maintains a copy of each catalog entry 
in a separate part of the volume, called the catalog recovery area (CRA). 

When you issue the LISTCRA command with the COMPARE parameter. 
Access Method Services compares each entry in the CRA to its corresponding 
entry in the catalog. The comparison is made on a record-by-record, 
byte-by-byte basis. When a mismatch is encountered within a record. Access 
Method Services determines the field within the record in which the mismatch 
exists and prints a message. For certain fields, the message identifies the 
field(s) which mismatched. (The section "Regaining Access to Data" lists the 
mismatches detected by LISTCRA.) 

When a mismatch is detected, Access Method Services prints both the catalog 
record and the corresponding CRA record. Asterisks are printed below the 
specific area which showed a mismatch. All records associated with the 
mismatched record are also printed (for example, a volume record and its 
extensions). You can use the LISTCRA output listing to determine which 
catalog entries are no longer accurate, and to help you code the ENTRIES 
subparameter of the EXPORTRA command. 

To use the LISTCRA command, Access Method Services must be authorized. 
See "Authorized Program Facility (APF)" in OS/VS2 System Programming 
Library: Supervisor for information about program authorization. 

The types of output listing that the LISTCRA command can produce, 
depending on the optional parameters, are: 

• A list of the name and vober of each entry, and the name and volser of 
each related entry, in the catalog recovery area. The entries are listed in 
alphameric order by group type (NOCOMPARE and NAME). 

• A full dump (that is, hexadecimal and character listing) of each entry and 
its related entries in the catalog recovery area. The entries are listed in 
alphameric order by group type (NOCOMPARE and DUMP). 

• A list of the name of each catalog entry and its volser whose data does not 
compare equally with the entry's copy in the catalog recovery area, and an 
indication of the type of information that miscompares. The miscompared 
entries are listed in alphameric order by group type. The entries that 
compare equally are not listed (COMPARE and NAME). 

• A full dump (that is, hexadecimal and character listing) of each catalog 
record whose contents does not compare equally with the record's copy in 
the catalog recovery area, and asterisks below each byte that mismatches. 
The mismatched entries are listed in alphameric order by group type. Refer 
to the section "Regaining Access to Data" in the chapter "Data Security 
and Protection" for a description of the types of mismatches detected by 
LISTCRA. The entries that compare equally are not listed (COMPARE 
and DUMP). 

• A full dump (that is, hexadecimal and character listing) of all entries in the 
catalog recovery area in sequential order as they occur in the CRA 
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(SEQUENTIALDUMP). "Appendix D: Interpreting LISTCRA Output 
Listings" provides a description of LISTCRA outputs. 

Refer to the chapter "Command Format" for a description of the command 
format of LISTCRA. An example is also included. "Appendix D: Interpretini 
LISTCRA Output Listings" provides a description of LISTCRA output. 



Copying a Catalog Entry From the Catalog Recovery Area 



When you discover that your catalog is partially or completely damaged due 
to a system failure or hardware problem, you want to reconstruct the 
damaged catalog entries so that you can access the cataloged object's data. . 
When you discover that some of the entries in your catalog are not in 
synchronization with volumes the catalog owns, you want to resynchronize 
the incorrect entries so they properly reflect the actual status of the volumes. 
You can rebuild a catalog entry by issuing the IMPORT command when you 
have recently made a copy of the object with the EXPORT command. The 
IMPORT command replaces the damaged catalog entry with its copy in the 
exported file. (See "Moving Entries" for details about the EXPORT and 
IMPORT commands.) 

An exported copy of your cluster might not exist, or the one you have might 
not be current. The volume that contains your data might not be damaged 
but, because its catalog entry is damaged or out-of-synchronization, you 
cannot use the catalog entry to locate and access your data. What you want to 
do is replace the damaged catalog entry with its undamaged copy in the 
catalog recovery area and, when the entry is for a VSAM data set, to move 
the contents of the data set to a volume owned by an undamaged catalog. For 
a recoverable catalog, you can use the EXPORTRA command to obtain the 
catalog-entry's copy from the catalog recovery area, then use the 
IMPORTRA command to replace the damaged entry with its copy. 

If an entire VSAM volume becomes unusable, and a backup copy of the 
volume exists, you may want to consider using RESETCAT rather than 
EXPORTRA to reset your catalog so that it will correctly access the VSAM 
data sets on the restored volume. See "Resetting Catalog Entries." 

To use the EXPORTRA command, Access Method Services must be 
authorized. See "Authorized Program Facility (APF)" in OS/VS^ Syxtem 
Programming Library: Supervisor for information about program 
authorization. 

When a VSAM data set is recovered using the EXPORTRA and IMPORTRA 
commands, the result is essentially the same as if the data set were backed up 
using the EXPORT and IMPORT commands. The differences in the process 
used to achieve this result are: 

• The data set's catalog entry is copied from a catalog recovery area instead 
of the VSAM catalog. 

• Many data sets can be recovered with one issuance of the EXPORTRA 
and IMPORTRA commands. 
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The EXPORTRA command copies VSAM catalog entries and the contents of 
nonempty VSAM data sets to a movable storage device (that is, a magnetic 
tape or demountable disk pack). Other capabilities of the EXPORTRA 
command that are not available as functions of the EXPORT command are: 

• All entries in a catalog recovery area can be. copied, including VSAM 
clusters and alternate index entries, VSAM user catalog connectors and 
their aliases (from a master catalog CRA only), GDG base entries, and 
nonVSAM entries and their aliases. The connection between a nonVSAM 
entry and its GDG base entry is mentioned in the copy. Page spaces are 
not copied. 

• You can copy the entries for an empty cluster or alternate, index. 

• You can obtain a copy of each entry in the catalog recovery area by issuing 
the EXPORTRA command once. Subsequently, you can replace all entries 
exported with the EXPORTRA command by issuing the IMPORTRA 
command once. 

• You can obtain the copy of one or more entries, as you specify, without 
obtaining the rest of the catalog recovery area. 

• When the catalog owns more than one volume, you can obtain the copy of 
each entry from one volume's catalog recovery area without obtaining 
entries from the catalog recovery areas of other volumes. 

Use of the EXPORTRA command is limited to a single execution per system 
at one time only. That is, multiple executions cannot be processed ' 
simultaneously. 

The EXPORTRA command uses the variable-blocked spanned sequential 
format (SAM RECFM = VBS) for its output data set. Each record contains 
an 8-byte header. Each data record of a VSAM relative-record data set 
contains an additional 4-byte header. EXPORTRA sets the maximum 
logical-record length of the output data set based on the largest maximum 
recordsize of all the VSAM data sets being copied. To determine the largest 
maximum record size, EXPORTRA uses the value specified via the maximum 
subparameter of the RECORDSIZE parameter of the DEFINE CLUSTER or 
ALTERNATEINDEX command when each of the data sets to be exported 
was defined. The resulting maximum logical record length of the output data 
set is as specified below: 

• If a VSAM relative record data set has the largest maximum record size, 
the greater of 280, or the largest VSAM record size + 12 

• If a VSAM key-sequenced or entry-sequenced data set has the largest 
maximum record size, the greater of 280, or the largest VSAM maximum 
record size + 8 

The resulting maximum logical-record length of the output data set is limited 
to 32,760 bytes (Access Method Services does not support the DCB 
parameter LRECL=X). Therefore, the largest VSAM record which can be 
handled by EXPORTRA is: 

• 32,748 for relative record data sets 

• 32,752 for all other types of VSAM data sets 

If any of the VSAM data sets to be exported has been defined with a 
maximum record size greater than that shown above, the EXPORTRA 
command terminates with an error message. 
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You may specify, with the DCB parameter of the DD statement for the 
portable data sets, a blocksize other than the default of 2048 bytes. 

If the EXPORTRA command is executed for a RACF-protected VSAM 
entity, the RACF indicator will be exported on to the portable data set. 
However, profiles will not be deleted, nor will the profiles be moved to the 
portable data set. When RACF-protected VSAM entities are imported using 
IMPORTRA, you have an option to reuse the old profiles or to establish new 
ones. 

The EXPORTRA command requires a DD statement for each volume to be 
accessed; all volumes must be mounted. EXPORTRA does not dynamically 
allocate the required volumes. 

Refer to the chapter "Command Format" for a description of the command 
format for EXPORTRA. Examples of EXPORTRA are included with the 
EXPORTRA command format in the same chapter. 



Restoring the Catalog Entry That Was Obtained Using the 
EXPORTRA Command 



The IMPORTRA command is used to reestablish in a catalog all those objects 
that reside in the portable data set created by a previously issued 
EXPORTRA command. When an existing catalog entry is found with the 
same entryname as the object in the portable data set, the existing entry is 
first deleted. The object is redefined in the catalog, using information from 
the portable data set. 

VSAM clusters, their associated data and index components, and any paths 
over them, alternate indexes, their associated data and index components, and 
any paths over them, nonVSAM data sets, and generation data group entries 
are automatically defined in the catalog selected by the user. If a VSAM 
cluster or alternate index was not empty at the time the EXPORTRA 
command was issued, its data records were copied to the portable data set 
together with its VSAM catalog entries. These data records are reloaded into 
the space occupied by the redefined object. User catalog connector entries 
(which can be exported only from the system's master catalog) are connected 
to the master catalog. (Existing user catalog-connector entries with the same 
entryname as the imported entry nre disconnected rather than deleted; the 
imported user catalog-connector entry is then reconnected.) The aliases of 
user catalog and nonVSAM entries are also redefined by IMPORTRA. 

IMPORTRA requires you to provide a DD statement (specified through the 
OUTFILE parameter) which identifies a data-set name and the volume serial 
number of each volume that is to contain the imported VSAM clusters or 
alternate indexes. You must use concatenated DD statements if the data sets 
are on different device types. The data-set name you specify is used by 
Access Method Services for its internal processing during the execution of the 
IMPORTRA command. The sequence of processing steps is shown below: 

1. The cluster or altefnate-index catalog information is obtained from the 
portable data set (created by EXPORTRA). 

2. The cluster or alternate index is defined in the catalog. 

3. If an existing catalog entry with the same entryname is found, the existing 
entry is deleted. The cluster or alternate index is then redefined in the 
catalog. 
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4. The cluster or alternate index entry in the catalog is renamed using the 
data-set name you provided in the DD statement identified in your 
OUTFILE parameter. 

5. The cluster or alternate index is opened, loaded with its data records, and 
closed. 

6. The cluster or alternate-index entry is renamed to the original name 
contained in the portable data set. 

If a system failure should occur after step 4 and prior to the successful 
completion of step 6, the data set may exist in the VSAM catalog under the 
name provided on the DD statement. To correct the situation, you can delete 
the cluster or alternate index using the data-set name you provided in the DD 
statement prior to rerunning the IMPORTRA command. 

Refer to the chapter "Command Format" for a description of the command 
format for IMPORTRA. Examples of EXPORTRA and IMPORTRA are 
included. 



Resetting Catalog Entries 



When you define a catalog as recoverable, each volume owned by the catalog 
contains a catalog recovery area (CRA). The CRA contains dupUcate 
information for catalog entries associated with that volume. You can use the 
RESETCAT command when a recoverable catalog or one or more of its 
owned volumes becomes inaccessible. You can restore the inaccessible 
volume(s) from a backup copy and execute the RESETCAT command. The 
CRAs contain enough information to reset the catalog entries, and VSAM 
data sets owned by that catalog can again be accessed correctly. 

Unlike the EXPORTRA/IMPORTRA command, the RESETCAT command 
is a one-step operation that enables you to recover your catalog without 
movement of data. The RESETCAT command does not check Or process the 
data itself, but compares catalog entries with CRA entries and resets as 
necessary in order to enable you to regain access to the data. You are 
responsible for ensuring that the data is at the correct level for your use. 

If a VSAM volume becomes inaccessible, and a backup copy of the volume is 
used to restore the volume to a previous level, the volume and the catalog 
may no longer be synchronized. A list created by the LISTCRA command 
(with COMPARE option) can indicate mismatches that require RESETCAT 
command to be run. The RESETCAT command can synchronize the catalog 
with the volume. After access to the data has been regained, the data sets on 
that volume can be brought up to the current level by rerunning the jobs that 
were run after the backup was taken. 

If a recoverable catalog becomes unusable, use the LISTCRA command to 
help analyze the problem (also see "Catalog Recovery"). If you are unable to 
access your data, restore the catalog volume. Then run the RESETCAT 
command to synchronize the catalog with its owned volumes. If volumes have 
been added since the catalog backup was made, RESETCAT can build these 
entries in the catalog from the volume's CRA. If volumes have been deleted 
since the last backup, use the DELETE SPACE (FORCE) command to 
delete the volume's space entries in the catalog and delete the data sets that 
resided on those volumes that are now marked unusable in the catalog. 

RESETCAT uses the entries in the catalog recovery area for each volume you 
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identify to synchronize the catalog with these volumes. The actions taken by 
RESETCAT to accomplish this synchronization are summarized below: 

• If an entry exists in the catalog but not in the CRA, the entry is deleted 
from the catalog. 

• If an entry exists in the CRA but not in the catalog, the entry is inserted 
into the catalog. 

• If, in adding an entry to the catalog a duplicate name is encountered, the 
entry to be added is renamed. If the data or index component of a unique 
cluster or alternate index is renamed, the corresponding format- 1 DSCB is 
also renamed. If a nonVSAM entry is renamed, the corresponding 
format- 1 DSCB is not renamed. 

• The data space accounting in the volume entry is checked against the 
Volume Table of Contents (VTOC). 

- If the VTOC contains a format- 1 DSCB for VSAM space but the CRA 
volume entry does not reflect this space, the format- 1 DSCB is 
scratched. 

- If the CRA shows space which is not reflected in a format- 1 DSCB, the 
space is deleted from the CRA volume entry and the VSAM data sets 
which were shown as being contained within the space are marked 
unusable. 

- If the extents in the CRA volume entry do not match those in the 
associated format- 1 DSCB, the CRA is adjusted. 

• A space consistency check is performed to ensure that the space claimed 
by a VSAM data set has the correct extents. If a data or index component 
claims space that is not aUocated to VSAM, the component is marked 
unusable. If a data or index component claims space which is in conflict 
with another claim, the component in error is marked unusable and all 
space not shown as claimed wUl be returned for suballocation. 

• An association check is performed to ensure completeness of the 
structures; for example, a cluster entry must be correctly associated with its 
data and index components. When a structure is found to be incorrect, it is 
deleted and its space returned for suballocation. If a base cluster 
association is incorrect, the entire structure (base cluster, all alternate 
mdexes, and paths) is deleted. If an index structure is incorrect, only the 
alternate alternate-index structure and its paths are deleted. 

Whenever RESETCAT takes action as indicated above, you are informed 
with appropriate messages. 

If your catalog becomes unusable and no backup copy is available, you can 
use RESETCAT to recover all of your catalog entries: 

If the catalog is a user catalog, remove the catalog connector entry of your 
catalog from the master catalog via EXPORT DISCONNECT, and define 
a catalog with the same name on a different volume with the 
RECOVERABLE attribute. The new catalog can be on a different device 
type. You may specify a different allocation from that of the original 
catalog. Volumes owned by the unusable catalog should not be included as 
owned by the new catalog. The DEFINE operation would flag this as an 
error condition, because volumes are already owned. 

With this new catalog, issue RESETCAT, specifying all volumes owned by 
the previous catalog (including the unusable catalog's resident volume) for 
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reset. Because the new catalog name is the same as the old catalog name, 
all entries in the specified CRAs will be added to the new catalog 
(including volume entries). At the conclusion of RESETCAT processing, 
the old catalog will have been deleted and the space freed for 
suballocation. 

While the catalog is always updated during RESETCAT processing, the CRA 
can also be updated under certain circumstances. If some external event such 
as a power failure were to cause RESETCAT to fail, partial updates to the 
catalog and CRA(s) may have taken place. Therefore the catalog and any 
CRA volumes being reset should be restored before RESETCAT is rerun. It 
is advisable, therefore, for you to have backup volumes of your catalog and 
CRA(s) before you use RESETCAT. 

Prior to running RESETCAT, you may also wish to execute a LISTVTOC for 
the volumes to be used in the reset operation (because the VTOC may be 
changed by RESETCAT). Also, you may wish to execute a LISTCAT 
command for the catalog to be reset. 

After RESETCAT processing has completed, you should examine the 
messages it has issued. These messages describe specific actions taken by 
RESETCAT, such as marking a data set unusable or deleting an incorrect 
VSAM structure. You may also find it advisable to execute a LISTCRA 
command with the COMPARE option to verify that no further mismatches 
exist. 

Any further action you should take depends on each message issued by 
RESETCAT. If a data set has been marked unusable, the data that is 
accessible can be copied using the REPRO command. Data sets marked 
unusable can be deleted using the DELETE command. If renaming has taken 
place, you may wish to alter the name selected by RESETCAT to a more 
meaningful name using the ALTER command with the NEWNAME option. 

Refer to the chapter "Command Format" for a description of the command 
format of RESETCAT. Examples are also included. 



In planning to use RESETCAT, you should be aware of the following 
requirements: 

• Access Method Services must be authorized. See "Authorized Program 
Facility (APF)" in 0S/VS2 System Programming Library: Supervisor for 
information about program authorization. 

• The catalog being reset must be capable of being opened, and it must have 
the RECOVERABLE attribute. It may or may not have valid entries. 

• The CRAs must be capable of being opened. Entries not related to the 
CRA itself may be inaccessible. 

• The CRAs must have been created by a recoverable catalog with the same 
name as the catalog being reset. 

• The catalog must be extendable in the event that it becomes enlarged as a 
result of the reset operation. 

• If the master catalog is password protected, the master password of that 
catalog is required. 

• The master catalog may not be reset while it is in use as a master catalog. 
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No VSAM data sets cataloged in the catalog being reset can be open. 

You need to use caution when using RESETCAT to recover accessibility 
of a volume which contains a portion of a multivolume file. Prior to issuing 
RESETCAT, compatible levels of volumes containing multivolume files 
should be restored. See "Considerations for Multivolume Data Sets" in this 
chapter for more details. 



WORKFILE Space Requirements 



The RESETCAT command requires a temporary work file for use as 
temporary storage while processing the command. It is defined by the 
RESETCAT command in a catalog other than the one being reset and deleted 
at the end of command processing. The space required is subaUocated from 
VSAM data spaces on the volumes assigned on the DD statement for the 
WORKFILE parameter. Under normal conditions (no extensions), the 
amount of space required will be no larger than the resultant catalog. You can 
determine this by a LISTCAT listing of that catalog. 

If the catalog must be extended as a result of RESETCAT processing (this 
may occur when the catalog is restored at a lower level than its owned 
volumes), enough data space must be provided to allow for this extension. 
The space required for each extension is 6603 records, where the record size 
is 505 bytes. An additional 7 bytes per record will be required; the CI size 
will be set at 512 bytes. 



Considerations for Multivolume Data Sets 



The contents of a volume's CRA depend on the types of objects the volume 
contains. It is important for you to understand on which CRA the catalog 
information resides for a particular object. Figure 6 in this chapter identifies 
by object type the location of the CRA. 

The primary CRA contains all of the catalog records necessary to describe the 
object. Hence, for an entry sequenced data set on two volumes, the volume 
that contains the first part of the entry-sequenced data set contains all the 
records that describe the entry entry-sequenced data set (including its 
allocation on the second volume). The second volume, a secondary CRA for 
this object, contains information that shows that the entry-sequenced data set 
is allocated on the soCuuu vumme. If me second volume has an I/O error that 
renders it useless and a previous version of that volume is restored, the 
present catalog information may be eironeous; that is, the catalog may reflect 
the data set's extent on the second volume, whereas there is no longer an 
extent on the second volume. Prior to issuing a RESETCAT command, you 
should restore compatible levels of volumes containing multivolume data sets. 
RESETCAT would then be issued to reset the catalog to reflect the restored 
level of all data sets on all reset volumes. 

If, in the above example, the second volume was restored and RESETCAT 
specified only that volume as a reset volume, the entry-sequenced data set 
may be marked unusable for that volume and the space allocated to it would 
be either scratched or returned to the catalog for suballocation. The primary 
description is on the first volume, which was not indicated as one to reset. 
The description of the data set used would be the description that currently 
resides in the catalog. If the data set is defined differently on the second 
volume (for example, extents do not match), the data set is marked unusable 
for that volume and the allocated space marked free. 
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For a multivolume entry sequenced data set, a multivolume key-sequenced 
data set, or an alternate index defined on a volume different from the data set 
it is based on, minimizing the intersection of different multivolume data sets 
on a common volume will permit better use of RESETCAT. 

When all volumes of a multivolume VSAM data set or structure are not 
specified in the RESETCAT operation, the extent of checking depends on 
whether the primary CRA volume is specified for reset. If the primary CRA 
volume is specified for reset, all information in the catalog is replaced for the 
data set concerned. For all volumes of the multivolume data set, whether 
specified or not, the following consistency checks are made by RESETCAT: 

• Check the current catalog (if the volume is not specified) or the CRA (if 
the volume is specified) to ensure that the data set is defined on the 
volume. 

• Check the data set specified on each volume. Was it defined at the same 
time as the one specified in the primary CRA? 

• Check the extents described on the volumes. Are they still allocated to the 
multivolume VSAM data set? 

Although the above checks guarantee that the catalog physically describes a 
data set correctly, these checks cannot guarantee that the level of data in the 
data set is at a consistent level. For instance, if a multivolume 
keyed-sequential data set was defined with the data on one volume and the 
index on another, the same Define-time would be associated with both. If, 
over some time, several additions, deletions, and updates were made without 
causing an extension of the data set, RESETCAT would be unable to 
distinguish among different combination of volumes taken from this time 
period. Since the index contains direct VSAM pointers to the data, and 
inconsistent combination may cause errors. 

If the primary CRA volume is not specified for reset, the scope of checking is 
limited to volumes specified in the reset. The current catalog is checked to 
ensure that the current catalog entry describes the part of the data set on the 
reset volume. Hence, only verification (no reset) occurs for these partial 
entries. The check ensures that the part of the data set on the reset volume 
resides on the same physical place as described in the current catalog and is 
part of the same definition as the data set described in the current catalog. 
RESETCAT cannot guarantee that the level of data in the data set is at a 
consistent level among different volumes. 



For the catalogs required during RESETCAT processing, the catalog being 
reset (indicated by the CATALOG parameter of the RESETCAT command) 
must appear in a STEPCAT or JOBCAT DD statement. The catalog in which 
the work file is defined (optionally indicated by the WORKCAT parameter) 
must appear in a STEPCAT or JOBCAT DD statement. If the WORKCAT 
parameter is not specified, the work file will be defined in the catalog " 
specified in the first concatenation of the STEPCAT or JOBCAT DD 
statement. 



) 
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The relationship of the STEPCAT or JOBCAT DD statement is summarized 

below: 

I 

1. If you want the work file defined in a catalog other than the master 

catalog, then that catalog must be specified first in the JOBCAT or 
STEPCAT DD statement concatenation. 

//STEPCAT DD DSN=workcat ,DISP=SHR • 
// DD DSN=resetcat,DISP=SHR 

The above example specifies the work file catalog and reset catalog, 
respectively, in the JOBCAT or STEPCAT DD statement for case (1). 

2. If you want the work file defined in the master catalog, then the master 
catalog must be specified by name via the WORKCAT parameter and, if 
specified in the STEPCAT or JOBCAT DD statement, must appear last in 
the concatenation sequence. 

//STEPCAT DD DSN=resetcat ,DISP=SHR 
// DD DSN=mastcat,DISP=SHR 

The above example specifies the reset catalog and master catalog, 
respectively, in the JOBCAT or STEPCAT DD statement for case (2). 

Further, the catalog being reset must be used by the RESETCAT command 
as a data set. A separate DD statement may be used for this catalog. It should 
specify only the catalog being reset and should not be concatenated to 
another catalog. For example: 

//DDCAT DD DSN=catname,DISP=OLD 

DISP=OLD should be specified to ensure exclusive use of the catalog. If no 
DD statement is suppUed, it will be dynamically allocated. 

For CRAs, a single DD statement is required for each volume containing a \ 

CRA if CRAFILES parameter of the RESETCAT conmiand is specified. For 
example: 

//DDCRA1 DD UNIT=3330,VOL=SER=XYZ,DISP=SHR 
//DDCRA2 DD UNIT=2314 , VOL=SER=ABC,DISP=SHR 

Unit affinity may be specified to reduce unit requirements. No two CRAs wiU 
be demanded concurrently by RESETCAT. 

For the work file, RESETCAT command requires a list of one or more 
volumes to ucfiiic a temporary VSAM daia set; no more tnan tive volumes 
may be specified. If no data-set name is provided, a system-generated data set 
name will be used. The following is an example of a work file DD statement: 

//FILEW DD DSN=A.WFILE,UNIT=( 3330,2 ),VOL=SER=(X,Y), 
// DISP=OLD,AMP='AMORG' 



134 OS/VS2 Access Method Services 



COPYING AND PRINTING 



The REPRO and PRINT commands are used to copy and print VSAM and 
nonVSAM data sets, and to copy VSAM catalogs. 



Copying Data Sets 



You use the REPRO command to do any of the following: 

Copy a VSAM data set into another VSAM data set. 

Copy a sequential data set into another sequential data set. 

Copy an alternate index as though it were a key-sequenced VSAM data 
set. 

Copy a SAM, ISAM, or VSAM data set (whose records are fixed-length) 
into an empty VSAM relative-record data set. 

Convert a sequential or indexed-sequential data set into a VSAM data set. 

Convert a VSAM or indexed-sequential data set into a sequential data set. 

Copy a data set — other than a catalog — to reorganize it. Data set 
reorganization is an automatic feature. 

Copy a non-recoverable catalog from one volume to another, for example, 
from a 2314 volume to a 3330 volume. 

Make a backup copy of a catalog. 

Reload a backup copy of a catalog. 

Merge two VSAM data sets. 

Throughout the remainder of the REPRO discussion, all of these functions 
will be referred to as copying. 

Refer to the chapter "Command Format" for a description of the command 
format for REPRO. Several examples are included. 

VSAM data sets used as either input or output must be cataloged. Sequential 
and indexed-sequential data sets need not be cataloged. 

If a sequential or indexed-sequential data set is not cataloged, you must 
include the appropriate volume and unit parameters on your DD statement. 
You must also supply a minimum set of DCB parameters when the input data 
set is sequential or indexed-sequential, and/or output data set is sequential. 
The following table shows the four key parameters. 

>y User Default If Not Supplied 

PS 

u 

None 

BLKSIZE for F or FB 

BLKSIZE-4 for V or VB 

Note that the one parameter which is not supplied by default is BLKSIZE; 
you must supply this value. The DCB parameters can be supplied via the 
DSCB or header label of a standard labeled tape; otherwise, they must be 
supplied via the DD statement. 



Parameters 


Must Be Supp 


DSORG 


IS 


RECFM 


F, FB, V, VB 


BLKSIZE 


blocksize 


LRECL 


Irecl 
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Access Method Services does not support records greater than 32,760 bytes 
for nonVSAM data sets (that is, LRECL=X is not supported). If the 
logical-record length of a nonVSAM input data set is greater than 32,760 
bytes, or, if a VSAM data set defined with a record length greater than 
32,760 is to be copied to a sequential data set, your REPRO command will 
terminate with an error message. 

Records in an indexed-sequential data set that have a fixed-length, unblocked 
format with a relative-key-position (RKP) of zero are preceded by the key 
string when used as input. Therefore, the records in the output data set must 
have a record length defined that includes the extended length caused by the 
key string. Also, to copy "dummy" indexed-sequential records (records with 
hexadecimal TF' in the first byte) you must specify the DUMMY option in 
the ENVIRONMENT parameter. 

Because data is copied as single logical records in either key order or physical 
order, automatic reorganization takes place. The reorganization can cause any 
of the following: 

• Physical relocation of logical records. 

• Alteration of a record's physical position within the data set. 

• Redistribution of free space throughout the data set. 

• Reconstruction of the VSAM indexes. 

Figure 7 describes how the records from the input data set are added to the 
output data set when the output data set is an empty or nonempty 
entry-sequenced, key-sequenced, sequential data set, or relative-record data 
set. 



Empty 

Entry-Sequenced/ 
Sequential 

Key-Sequenced 



Creates new data set in 
sequential order. 



Creates new data set in 
key sequence and builds 
an index. 



Non-Empty 

Adds records in sequential order to the 
end of the data set. (DISP=MOD must 
be specified for SAM sequential.) 

Merges records by key and updates the 
index. Records whose key duplicates a 
key in the output data set are lost, unless 
you specify the REPLACE option. 



Relative-Record 



Creates a new data set in Records from another relative-record 
relative-record sequence, data set are merged, keeping their old 



ucgiuiiiiig witli 1 



record numbers. A new record whose 
number duplicates an existing record 
number is lost, unless you specify the 
REPLACE option. Records from any 
other type of organization cannot be 
copied into a nonempty relative-record 
data set. 



Figure 7. Adding Records To Various Types of Output Data Sets 
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Note: The copy operation is tenninated if: 

• One physical I/O error is encountered while writing to the output data set, 
or 

• A total of four errors are encountered in any combination of the following: 

- Logical error while writing to the output data set 

- Logical error while reading the input data set 



- Physical error while reading the input data 



set 



When copying to a key-sequenced data set, the records to be copied must be 
in ascending order with no duplicates (within the input data set). With an 
entry-sequenced data set, the records to be copied can be in any order. 

REPRO causes Access Method Services to retrieve record numbers from a 
sequential, indexed-sequential, or VSAM data set and store them in VS AM 
format in key sequence, record-number sequence, or entry sequence, or store 
them in a sequential data set. When records are stored in key sequence, index 
entries are created and loaded into an index component as control intervals 
and control areas are filled up. Free space, as indicated in the data-set 
definition in the catalog, is left, and records are stored on particular volumes 
according to key ranges, if indicated in the definition. 

You can load all of the records in one job or load them in several jobs. In 
subsequent jobs VSAM continues to store records as before, extending the 
data set as required. 

To use your own program to load a key-sequenced data set, first sort the 
records (or build them) in key sequence, and store them with sequential 
access (the PUT macro). See OS/VS Virtual Storage Access Method 
(VSAM) Programmer's Guide to find out how to use the VSAM macros to 
write your own program to load records into a data set. 



Copying a Catalog 



\ 



The REPRO command can be used to copy a catalog from one volume to 
another. When using REPRO to copy a catalog, both the input and the output 
objects must be catalogs (that is, you must first define a catalog on the device 
that is to contain the newly-copied catalog). A catalog might be copied to 
move it to a faster device type or to optimize the catalog's allocation. 

The receiving catalog need not be of the same device type as the source 
catalog. The receiving catalog must be empty. That is, the receiving catalog 
cannot contain any entries other than the entries that describe the catalog and 
its data space. 

You cannot copy the contents of a nonrecoverable catalog into a recoverable 
catalog, and vice versa, nor can you copy a recoverable catalog into a 
recoverable catalog. To convert a nonrecoverable catalog into a recoverable 
catalog, you must export each VSAM data set (from the nonrecoverable 
catalog), then import it into the newly defined (recoverable) catalog. To 
convert a recoverable catalog into a nonrecoverable catalog or to copy a 
recoverable catalog into a recoverable catalog, you can either export each 
VSAM data set from the source catalog and then import it into the target 
catalog or use the EXPORTRA/IMPORTRA commands to accomplish the 
same thing on a volume basis. 

To use the REPRO command to copy a catalog. Access Method Services 
must be authorized. See "Authorized Program Facility (APF)" in 0S/VS2 
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Copy-Catalog Preparation 



System Programming Library: Supervisor for information about program 
authorization. 



In preparation for copying a catalog, you should determine the amount of 
space to be allocated in the receiving catalog. Part of the process of 
determining how to allocate space for the receiving catalog includes reviewing 
how space is allocated in the catalog to be copied. 

There is no method (besides dumping the catalog) that enables you to 
determine the size of the catalog's index set or high-key range. You can 
however, determine the size (that is, number of data records) of the low-key 
range. (When you define a catalog and include DATA(RECOR,DS...), the 
number of records you specify is the number of data records you want the 
low-key range to contain, unless you also specify an amount of space as a 
subparameter of INDEX.) One of the catalog's self -describing records (in the 
low-key range) is called the catalog-control record, or CCR. The CCR 
describes the free (or unused) control intervals in the catalog, and contains 
statistics about how the catalog is used. To print the CCR, issue the PRINT 
command (as shown below), specifying the name of the catalog as the input 
data set. 

PRINT INDATASET(ca^name ) - 
SKIP( 3 ) - 
COUNT ( 1 ) 

When catname identifies a user catalog, your job must include a JOBCAT or 
STEPCAT DD statement to describe and allocate the catalog. 

The CCR is printed in the "dump" format (an example of this format is 
included with the first example in "PRINT Examples"). The record's first 44 
bytes are its key value. The next byte is the character "L," which identifies 
the record as a CCR-type record. The next nine bytes are three 3-byte fields 
whose hexadecimal values specify: 

Contents 

The highest control interval number that can be assigned. 

The next control interval number to be assigned. 

The nuniber of deleted records (that is, the iiumuci ui 
control intervals that are unused because the entry they 
contained was deleted). 

To determine the number of records in the low-key range, you also need 
information contained in the catalog's data-component record in addition to 
the information contained in the CCR. To list the data-component record, 
issue the LISTCAT command as shown below: 

LISTCAT ENTRIES {catname) ALL 

Your job must include a JOBCAT or STEPCAT DD statement to describe 
and allocate the catalog. The name of the catalog's data-component record is 
shown in the listing as VSAM.CATALOG.BASE.DATA.RECORD. 

The number of records in the catalog is the same as the number of control 
intervals in the low-key range that currently contain either catalog records 
(both base and extension records) or free records. The formula to derive the 
number of records varies depending on whether the low-key range has only 
one extent or has more than one extent. Using the LISTCAT output, find the 
VOLUME group for the low-key range of the data component. This is the 



Displacement 

45 (X'2D') 


Syn 

A 


48 (X'30') 


B 


51 (X'33') 


C 
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information listed under the VOLUME heading where the LOW-KEY is 
shown as 00 and the HIGH-KEY is shown as 3F. Extents are shown under 
I the EXTENTS heading for this VOLUME group. By looking at the 

p EXTENTS information you can determine whether the low-key range has 

one or more than one extent. 

1. If the low-key range has one extent, the value of B obtained from the CCR 
is the number of records to use. 

2. If the low-key range has more than one extent, use the formulas shown 
below to obtain the number of records: 

a. For all low-key range extents except the last: 
((HIGH-RBA + 1) - LOW-RBA) / 512 

b. For the last extent: 

((B x 512) - LOW-RBA) / 512 

where: 

HIGH-RBA and LOW-RBA are the values obtained from the 
LISTCAT output for each extent, and B is the value obtained from the 
CCR. 

The sum of each a plus b, above, is the number of records to use. 

To the number of records derived from either 1 or 2 above, you should add 
the constant 19. This will allow for the fifteen self -describing records of the 
target catalog plus the four free records which are always reserved for VSAM 
catalog use at the end of the low-key range. The final result should be 
specified as the value for primary when you specify: 

^) DATA(RECORDS( primary [b secondary ])) 

on your DEFINE USERCATALOG command. 

You should keep in mind that the number of records derived from the 
formulas above includes any formatted free records. If the low-key range has 
only one extent, all control intervals which have never been used plus all 
control intervals that are unused because the entry they contained was deleted 
are formatted free records. The value contained in the CCR field described as 
C above includes both types of free records. If the low-key range has more 
than one extent, only those control intervals that are unused because the 
entry they contained was deleted, are formatted free records. This is the value 
contained in the CCR field described as C above. All formatted free records 
are copied from the source catalog to the target catalog by the copy catalog 
function. 

When you specify the space allocation for the receiving catalog in terms of 
RECORDS as described above, you are defining the smallest possible 
receiving catalog. The value contained in the CCR field described as C above 
of the source catalog will determine how many free records wiU exist in the 
receiving catalog. These records will be available to hold new entries. 

The symbols A, B, and C have no meaning except in the formulas described 
above, which yield the number of control intervals that contain catalog 
records in the low-keyrange. The complete format of the CCR record is 
included in Virtual Storage Access Method (VSAM) for 0S/VS2 MVS: 
Catalog Management Logic. See Planning for Enhanced VSAM Under 
\ OS/VS for more details about the catalog's structure and the low-key range. 

; 
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Copy-Catalog Procedure 



The following steps should be followed to copy a catalog: 

1 . Use the DEFINE command to define a catalog into which the source 
catalog is to be copied. The preceding section describes a method of 
detennining in records the smallest possible receiving catalog. 

The receiving catalog need not be of the same device type as the source 
catalog. The receiving catalog must be empty. That is, the receiving catalog 
cannot contain any entries other than the entries that describe the catalog 
and its data space. 

2. Use the REPRO command to copy the source catalog to the receiving 
catalog. You cannot specify any of the REPRO command's delimiters 
(FROMKEY, TOKEY, SKIP, or COUNT) when you use REPRO to copy 
a catalog. A concatenated JOBCAT or STEPCAT DD statement is 
required to describe and allocate both the source and receiving catalogs. 
When the master catalog is being copied (that is, the source is the master 
catalog), use a single JOBCAT or STEPCAT DD statement to describe 
and allocate the receiving catalog. A DD statement is not required to 
describe and allocate the master (source) catalog. 

3. Use the EXPORT conmiand to disconnect the source user catalog from the 
master catalog. This step is not necessary if the source catalog is the master 
catalog. 

If the source catalog was a user catalog, you should take care to list the 
aliases of the user catalog in the master catalog before you issue the 
EXPORT command. You can use the LISTCAT command to list the 
aliases: 

LISTCAT - 

CATALOG( mastercatname /password ) - 

ENTRIES( usercatname) - 

ALL 

The user catalog's aliases are listed under the heading "ASSOCIATIONS." 

If you use the IMPORT command to make the catalog available to another 
system, you can issue the DEFINE ALIAS command to reestablish each of 
the c^italog's aMsses. 

4. If the source catalog was a user catalog, use the DEFINE ALIAS command 
to establish the required aliases of the receiving catalog. 

5. Use the DELETE command to remove the source catalog from the 
receiving volume. The source catalog appears in the receiving catalog as a 
cluster as a result of the copy operation. 

The copy-catalog procedure should be performed with caution. Until the 
source catalog is disconnected from the master catalog, two catalogs are 
available for use. 
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Backing Up a Catalog 



At the completion of the copy-catalog procedure: 

• The DSCB on the source-catalog volume is modified so that it no longer 
indicates that the volume contains a catalog (step 5). 

• A volume entry is created in the receiving catalog for the source-catalog 
volume; the source-catalog volume is owned by the receiving catalog (step 
2). 

• Space used by the source catalog is made available for suballocation (step 
5). 

If you are copying the master catalog, special care should be taken that the 
job is executed when the system is otherwise quiesced. Otherwise, it is 
possible that updates could be made to the master catalog during the copy. To 
use the target catalog as a master catalog, the following steps should be taken 
following step 2 described above: 

• Replace the SYSCATLG member in SYS 1. NUCLEUS (now cataloged in 
the target master catalog) so that the SYSCATLG member points to the 
new master catalog ("Appendix G: Changing the Attributes of the VSAM 
Master Catalog" gives an example of how to replace SYSCATLG). 

• RelPL the system. With the SYSCATLG member changed, the IPL will 
reference the new master catalog, 

• Proceed vdth step 5 described above. 



You can use the REPRO command to unload a VSAM catalog into a 
key-sequenced, entry-sequenced, or sequential (SAM) data set. If the catalog 
becomes inaccessible, you can redefine the catalog and use REPRO to reload 
the backup to replace it. If the catalog is accessible, you can use REPRO to 
reload the backup and reestablish catalog entries. Reloading a catalog should 
be done judiciously since it is difficult to recover VSAM data spaces, page 
spaces, and data sets that have extended after a backup copy of the catalog 
was made. 

Using REPRO to unload or reload a password-protected catalog requires the 
catalog's master password. 

The parameters that limit the extent of copying are invalid for unload/reload. 
Parameters that indicate action on the output data set are also invalid. These 
parameters are: COUNT, FROMKEY, FROMNUMBER, FROMADDRESS, 
SKIP, TOKEY, TO ADDRESS, TONUMBER, REUSE and REPLACE. 

Use a STEPCAT DD statement to identify the catalog that you are loading or 
reloading. 

Do not allow the catalog to be updated during the operation. (REPRO does 
not itself prevent other processing of the catalog.) 

To use the REPRO command to unload or reload a catalog. Access Method 
Services must be authorized. See "Authorized Program Facility (APF)" in 
0S/VS2 System Programming Library: Supervisor for information about 
program authorization. 



^ 
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Unloading a Catalog 



Reloading a Catalog 



A sequential, key-sequenced, or entry-sequenced backup copy of a catalog is 
inaccessible as a catalog. Because there is little advantage in having the 
backup on a direct-access volume, you can most conveniently use magnetic 
tape to copy a catalog in a sequential data set. 

To unload a catalog into a key-sequenced or entry-sequenced data set, first 
define the data set in another catalog (for protection). 

To continually have a recent backup copy available, you should unload a 
catalog periodically. With tape, you can easily alternate two or more volumes 
for several levels of backup. 

Use LISTCAT before unloading a catalog. You can compare the listing with 
the one you obtain after reloading. If you are unloading a recoverable catalog, 
use LISTCRA with the COMPARE option to ensure that the catalog and its 
volumes are synchronized at the time of the unload operation. 

Example 3 in the section "REPRO Examples" describes the DCB parameters 
you must specify on your DD statement if you unload your catalog to a 
nonVSAM sequential (SAM) data set. 



You must use REPRO to reload the backup copy into a catalog (the "target") 
with the same name, volume-serial number, and device type as the original 
catalog. Reloading the master catalog has special requirements (for details, 
see the section "Backing Up the Master Catalog" in the chapter "Data 
Security and Protection.") 

The target catalog can be either a version of the original catalog (which might 
have been obtained using lEHDASDR RESTORE), or a newly defined user 
catalog (after using EXPORT DISCONNECT to remove the user catalog 
entry in the Master Catalog). The primary allocation of the newly defined 
catalog must be able to hold at least as many records as the original catalog 
held at the time the backup copy was made. Catalog extension will not take 
place during the reload operation. If the newly defined catalog is not large 
enough, your reload job wUl fail. The same method as that described in 
"Copy-Catalog Preparation" in this chapter can be used to determine the 
smallcsi pussibic size of the newly defined catalog. However, you must make 
the calculations based on the original catalog at the time the backup was 
made. 

Reloading a version of the original catalog results in a catalog equivalent to 
the original one at the time the backup was made. Reloading replaces entries 
in the target catalog with entries of the same name in the backup. It inserts 
into the target entries that exist only in the backup. It deletes from the target 
entries that exist only in the target. During reloading. Access Method Services 
issues a maximum of one hundred messages to indicate entries that exist only 
in the target or only in the backup. 

Reloading a newly defined catalog has the same results as reloading a version 
of the original catalog, with one exception. The newly defined catalog's 
Volume record contains only self -defining information. A check is initiated 
when reload opens the catalog and, if the catalog is new, a reload of the 
original version of the Volume record is bypassed. (The assumption is that, if 
the catalog is new, no other VSAM data space exists on the volume under 
normal conditions.) The Volume record of the original version of the catalog 
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contains all the data space information previously on the volume at the time 
the catalog was unloaded. But, when the reload of the Volume record is 
bypassed, the data space infonnation is lost. After the reload of a newly 
defined catalog, the entries in the reloaded catalog-reference data sets 
previously existing on the volume. If these data sets still exist, they can be 
accessed, but any attempt to extend the data space in which they reside wUl 
fail. In this situation, you can restore all needed information to the Volume 
record by, first, using EXPORT PERMANENT to remove the data set entries 
from the new catalog, then define a data space large enough to accommodate 
the data sets, and then use IMPORT to put the data sets into the newly 
defined data space. 

After you reload a catalog, use LISTCAT to list its contents. Run LISTCAT 
in a separate job step, so that the catalog will be closed after it is reloaded (to 
update its self -defining information). Compare the listing with the one you 
obtained before unloading the original catalog to ensure that you have used 
the right backup. 

Reloading or restoring a recoverable catalog does not cause the catalog 
recovery area to be updated. Therefore, the LISTCRA command with 
COMPARE option should be run to identify mismatches between the catalog 
and the catalog recovery area (CRA). (This should be done in a separate job 
step, immediately after the reload.) These mismatches should be resolved as 
necessary before the catalog can be used. (See the section "Catalog 
Recovery" in the "Data Security and Protection" chapter.) No other jobs 
should be run after the reload and before the LISTCRA if these jobs access 
any of the data sets cataloged in the reloaded catalog. 

If VSAM data sets or data spaces have been deleted or permanently' exported 
since the last catalog backup and the catalog is reloaded or restored, then the 
deleted data sets or data spaces will stiU be defined in the restored catalog. 
Any attempt to process these entries will yield unpredictable results because 
the space reflected in the catalog may no longer be owned by the catalog. The 
catalog may be corrected by reissuing the DELETE commands. 

If VSAM data sets or data spaces have been defined or imported since the last 
catalog backup and the catalog is reloaded or restored, then the defined data 
sets or data spaces will not be defined in the reloaded or restored catalog. 
Processing these data sets or data spaces by means of the restored catalog is 
not possible since they cannot be accessed. The space formerly occupied by 
these VSAM data sets or data spaces will not be usable, but may be recovered 
by scratching the format- 1 DSCBs in the VTOC for the data spaces. If any 
volumes were added to the catalog (between the backup and the recovery), 
they will also be unusable untU you use the DELETE command with FORCE 
option or ALTER REMOVE VOLUMES to give up volume ownership. 

If a VSAM data set has been extended since the last catalog backup, the new 
extents will not be defined in the restored or reloaded catalog. Any attempt to 
process records in the added extents wUl result in a logical error. If the data 
set has been extended within space already allocated to the data set before 
the backup but has acquired no new extents, then you can issue the VERIFY 
command to update the catalog pointers, and the data set may be accessed 
normally. 

The data in any extents that have been acquired by the data set since the 
catalog was backed up is unrecoverable. For an entry-sequenced data set the 
data in any new extents should consist only of records that have been added 
to the end of the data set. Therefore, it is possible to recover all of the data in 
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the old extents by accessing the data set sequentially up to the end of the old 
physical space allocation. For a key-sequenced data set, the new extents may 
be any portion of the data set because of control-area splits. An attempt to 
read the data in logical sequence will fail with an invalid RBA indication when 
the data in the new extents is reached. You could access the key-sequenced 
data set by means of address sequence, but you then have the problem of 
identifying the missing records. Individual data set recovery for those data 
sets affected will be necessary. 

See the section "Updating a Backup Catalog" in the chapter "Data Security 
and Protection" for a discussion of making the contents of the backup catalog 
agree with the contents of the original catalog at the time it became 
inaccessible. 

Optimizing the Performance of Unload /Reload 

You can specify additional I/O buffers for unloading and reloading by using: 

• The AMP parameter in the STEPCAT DD statement that identifies the 
catalog — AMP= 'BUFND=x, BUFNI=2', where x equals 2 times the 
number of 5 1 2-byte control intervals per track of the device used for the 
catalog. 

• The AMP parameter in the DD statement that identifies a key-sequenced 
or entry-sequenced backup copy — AMP= 'BUFND=x, BUFNI=2', where 
X equals 2 times the number of 51 2-byte control intervals per track of the 
device used for the backup. 

• The DCB parameter in the DD statement that identifies a sequential 
backup copy — DCB=BUFNO=x, where x equals either: 

- 2 times the number of 51 2-byte control intervals per track of the device 
used for the catalog (when the backup is on magnetic tape) or 

- 2 times the number of physical records per track of the device used for 
the backup (when the backup is on a direct-access volume). 

Block the records in a sequential backup data set. Some catalog records are 
47 bytes long; the rest are 505 bytes long. Use DCB=RECFM=VB. 



Printing Data Sets 



NT command io list part or ail of a key-sequenced, 
relative-record, or entry-sequenced VSAM data set, an alternate index, a 
VSAM catalog, or a nonVSAM data set. The components of a key-sequenced 
data set or alternate index can be listed individually. To list a component of a 
key-sequenced data set or alternate index, specify the component name as the 
data set name. An alternate index is printed as though it were a 
key-sequenced cluster. 

If a sequential or indexed-sequential data set is not cataloged, you must 
include the appropriate volume and unit parameters on your DD statements. 

You must also supply a minimum set of DCB parameters when the data set to 
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Parasneters 


Must Be Supp 


DSORG 


IS 


RECFM 


F, FB, V, VB 


BLKSIZE 


blocksize 


LRECL 


Irecl 



be printed is sequential or indexed-sequential. The following table shows the 
four key parameters: 

Sy User Default If Not Supptied 

PS 

u 

None 

BLKSIZE for F or FB 

BLKSIZE-4 for V or VB 

Note that the one parameter which is not supplied by default is BLKSIZE; 
you must supply this value. The DCB parameters can be supplied via the 
DSCB or header label of a standard labeled tape; otherwise, they must be 
supphed via the DD statement. 

Access Method Services does not support records greater than 32,760 bytes 
for nonVSAM data sets (that is, LRECL=X is not supported). If the logical 
record length of a nonVSAM input data set is greater than 32,760 bytes, your 
PRINT command will terminate with an error message. 

Sequential and entry-sequenced data sets are listed in physical sequential 
order. Indexed-sequential and key-sequenced data sets can be listed in key 
order or in physical sequential order. A base cluster can be listed in 
alternate-key sequence by specifying a path name as the data-set name for the 
cluster. 

Only the data content of logical records is listed. System defined control fields 
are not listed. Each record listed is identified by one of the following: 

• Its relative byte address (RBA) for entry-sequenced data sets, 

• Its key for indexed-sequential (ISAM) and key-sequenced data sets, and 
for alternate indexes. 

• Its sequential record number for sequential (nonVSAM) and 
relative-record data sets. 

Note: If four logical and/or physical errors are encountered while trying to 
read the input, the printing is terminated. 

To use the PRINT command to print a VSAM catalog, Access Method 
Services must be authorized. See "Authorized Program Facility (APF)" in 
OS/ VS2 System Programming Library: Supervisor for information about 
program authorization. 

Refer to the chapter "Command Format" for a description of the command 
format for PRINT, Examples of the PRINT command are included. 
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LISTING TAPE VOLUMES MOUNTED AT 
CHECKPOINT 






OS/VS Checkpoint/ Restart explains taking checkpoints and restarting 
programs. Here is a summary: 

During processing, a program can issue the CHKPT macro to record various 
information for use in restarting the processing if an error prevents the 
program from continuing. Recording information by way of CHKPT is called 
taking a checkpoint. The records that contain the information make up a 
checkpoint entry in the checkpoint data set, which contains an entry for each 
checkpoint that is taken. 

The checkpoint data set can be a sequential data set or a partitioned data set. 
In a partitioned data set, each checkpoint entry is a member of it. 

Checkpoint information includes the volume serial numbers of tape data sets 
that were open at the checkpoint. The CHKLIST command enables you to 
list these volume serial numbers to identify the tape data sets that need to be 
mounted for restart. 

For a checkpoint data set with DSORG=PS (sequential data set), you can 
select one or more specific checkpoint entries for which the tape information 
is to be listed by a single CHKXIST command. By not selecting any specific 
entry, all checkpoint entries will be processed. 

You can use CHKLIST to process a checkpoint data set with DSORG=PO 
(partitioned data set) in the following manner: 

• Specify DSN AiME=dsname(member) on the JCL statement that defines 
the checkpoint data set. 

• Do not select a specific checkpoint entry, so that the single entry specified 
by member after dsname will be processed. 

The CHKLIST command causes the following information to be listed: 

• The checkpoint identifier for the entry being processed. 

• For each tape data set that was open at the time of the checkpoint, the 
following items are listed: 

- dsname 

- DD name 

- type of unit on which the volume was mounted 

- the sequence number of the mounted volume 

- volume serial numbers with an * by the volume serial number of the 
mounted volume. 

To process multiple members of a partitioned checkpoint data set, use the 
CHKLIST command once for each member. 

Note: The CHKLIST command caimot be invoked as a TSO command. 

Refer to the chapter "Conmiand Format" for a description of the command 
format for CHKLIST. Examples of the CHKLIST command are also 
included. 
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COMMA>fD FORMAT 



This chapter sets out the functional command formats. Parameters are 
grouped into categories such as name, data organization, allocation, and 
protection and integrity. The format of each command is then shown, 
followed by a discussion of each parameter. Examples of each command 
follow the parameter discussion. 



Functional Command Format 



This section provides complete reference information about all functional 
commands of Access Method iServices. The commands discussed in the 
section are: 

• ALTER command, which is used to alter attributes of data sets and other 
objects that have already been defined. 

• BLDINDEX command, which is used to build an alternate index over a 
base cluster. 

• CHKLIST command, which lists tape data sets opened during a 
checkpoint. 

• CNVTCAT command, which converts OS catalog entries to VSAM 
catalog entries and merges them into a VSAM catalog. 

• DEFINE ALIAS command, which is used to define an alternate name for a 
nonVSAM data set or a user catalog. 

. DEFINE ALTERNATEINDEX command, which is used to define an 
alternate index. 

• DEFINE CLUSTER command, which is used to define a cluster for a 
key-sequenced, entry-sequenced, or relative-record data sets, 

. DEFINE GENERATIONDATAGROUP command, which is used to 
create a catalog entry for a generation data group. 

• DEFINE NONVSAM command, which is used to define a catalog entry 
for a nonVSAM data set. 

• DEFINE PAGESPACE command, which is used to define an entry for a 
page space data set. 

• DEFINE PATH command, which is used to define a path directly over a 
base cluster or a path over an alternate index and its related base cluster. 

• DEFINE SPACE command, which is used to define a VSAM data space. 

. DEFINE USERCATALOG command, which is used to define a VSAM 
user catalog. 

• DELETE command, which is used to delete data sets and other objects, 
including catalogs and nonVSAM data sets. 

• EXPORT command, which is used to export VSAM files and to disconnect 
user catalogs. 

• EXPORTRA command, which is used to recover VSAM and nonVSAM 
catalog entries from catalog recovery areas and, for VSAM objects 
(clusters and alternate indexes), to recover the data itself by means of 
catalog recovery areas. 
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• IMPORT command, which is used to import VSAM data sets and to 
connect user catalogs. 

c IMPORTRA command, which is used to reconstruct multiple VSAM data 
sets from a data set created by the EXPORTRA command. 

• LISTCAT command, which is used to list catalog entries. 

. LISTCRA command, which is used to list or compare the contents of a 
given catalog recovery area. 

• PRINT command, which is used to print both VSAM and nonVSAM data 
sets. 

• REPRO command, which is used to copy and load both VSAM and 
nonVSAM files and VSAM catalogs. 

• VERIFY command, which is used to verify and correct certain problems 
that have made your data set unusable. 

See "Notational Conventions" in the "Preface" (About This Book) for an 
explanation of the symbols used in the command formats. 
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ALTER 



ALXER. 



The format of the ALTER command is: 



ALTER 



entryname ypassword\ 

[ADDVOLUMES( wiser [ b vober ...])] 

[ATTEMPTSC number )] 

[ AUTHORIZATIONC entrypoint [ b string ])] 

[BUFFERSPACE(5ize )] 

[CODEC co/e)] 

[CONTROLPW(paJ5wor J )] 

[DESTAGEWATT | NODESTAGEWATT] 

[EMPTY I NOEMPTY] 

[ERASE I NOERASE] 

[EXCEPTIONEXrrCenf rK/?omr )] 

{¥aJEidname)\ 

[FREESPACEC CI-percent{h CA-percent ])] 

[INHIBIT I UNINHIBIT] 

[KEYS(/engr/i b offsety\ 

{MASmW?V^{password )] 

[NEWNAME( newname )] 

[NULLIFY( 

[AUTHORIZATIONCMODULE | STRING)] 

[CODE] 

[CONTROLPW] 

[EXCEPTIONEXrr] 

[MASTERPW] 

[OWNER] 

[READPW] 

[RETENTION] 

[UPDATEPW])] 
[OWNERiownerid)] 
[READFW(password)] 
[RECORDSIZEC average b maximum )] 
[REMOVEVOLUMESC volser[h volser ...])] 
[SCRATCH I NOSCRATCH] 
[SHAREOPTIONS(craMreg/on [b crosssystem ])] 
[STAGE I BIND | CYLINDERFAULT] 
[TO(date)\FORidays}] 
[UNIQUEKEY | NONUNIQUEKEY] 
[UPDATE I NOUPDATE] 
[VFDATEPmpassword)] 
[UPGRADE I NOUPGRADE] 
[WRTTECHECK | NOWRTTECHECK] 

[CATALOGC catname [/password ])] 



Command Format 151 



ALTER Parameters: Summary 



The parameters of the ALTER command are described in the following 
groups: 

• Name, which describes the entryname and NEWNAME parameters. These 
parameters are used to name the entry to be altered and, optionally, to 
rename the entry. These parameters are also used to rename a member of a 
nonVSAM partitioned data set. 

• Protection and integrity, which describes the NULLIFY, MASTERPW, 
CONTROLPW, UPDATEPW, READPW, UNINHIBIT, INHIBIT, 
CODE, ATTEMPTS, AUTHORIZATION, EXCEPTIONEXIT, OWNER, 
TO, FOR, SHAREOPTIONS, ERASE, NOERASE, ERASE, NOERASE, 
WRITECHECK, NOWRITECHECK, DESTAGEWAIT, and 
NODESTAGEWAIT parameters. These parameters are used to alter 
protection and integrity attributes. 

. Allocation, which describes the FILE, FREESPACE, BUFFERSPACE, 
RECORDSIZE, KEYS, ADDVOLUMES, REMOVE VOLUMES, 
STAGE, BIND, and GYLINDERFAULT parameters. These parameters 
are used to modify the amount of free space to be left in control intervals 
and control areas, to modify the amount of buffer space to be provided, to 
add and remove volumes from the list of volumes to be used as overflow 
volumes, and to modify the indication of how a data or index component 
that is stored on a mass-storage volume is to be staged. 

When a data set does not contain any data records, RECORDSIZE can be 
specified to modify the data set's average and maximum record sizes. 
When a key-sequenced data set or alternate index is empty, KEYS can 
respecify the the length and position of each data-record's key field. 

• Alternate index and path, which describes the UNIQUEKEY, 
NONUNIQUEKEY, UPDATE, NOUPDATE, UPGRADE, and 
NOUPGRADE parameters. These parameters specify attributes that apply 
only to alternate index and path entries. 

• Generation-data-group attributes, which describes the EMPTY, 
NOEMPTY, SCRATCH, and NOSCRATCH parameters. These 
parameters are used to alter what is to happen when the maximum number 
of ffeneration data sets is reached. 

• Catalog, which describes the CATALOG parameter. This parameter is 
used to name the catalog in which the entry to be altered is defined. 



Entry-Types That Can Be Altered 



An "X" in Figure 8 indicates you can respecify the value or attribute for that 
type of VSAM catalog entry. Some attributes, when specified for a cluster or 
alternate index, apply to its data or index component entry only, and not to 
the cluster or alternate-index entry. Some attributes can only be specified for 
the cluster's or alternate-index's data or index component entry — you must 
identify the component's entry with its entryname. You can use the Access 
Method Services LISTCAT command to determine the names VSAM 
generated for the object's components. 

When you identify a group of entries with a generic name, entries whose 
entrynames match the suppUed qualifiers are altered, if they contain the type 
of information specified with the ALTER command's other parameters. 
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Type of Catalog E^try: 

ALTERNATE INDEX 
DATA INDEX 



CLUSTER 

DATA INDEX 



PGSPC PATH UCAT NonVSAM GDG 
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X 




X 


X 












ATTEMPTS 


X 


X 


X 


X 


X 


X 


X 


X 


X 
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Figure 8. ALTER Parameters and the Entry-Types to Which Each Applies 
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You cannot identify the following t3rpes of entries: alias entries, a catalog's 
data or index-component entries. 



ALTER Parameters 
Required Parameters 



Optional Parameters 



entryname [ / password ] 

is a required parameter that names the entry to be altered and supplies a 
password. See the section "Generic Names and ALTER" for a description 
of how to specify a generic name in order to alter multiple entries with one 
ALTER command. 

If you are renaming a member of a nonVSAM partitioned data set, the 
entryname must be specified in the format: pdsname(membemame). 

If you are altering a password-protected entry in a password-protected 
catalog, you must specify a password. The password can be specified with 
entryname or in the CATALOG parameter. For the following entry types, 
the password must be the master password for the entry or for the catalog 
that contains the entry: alternate index, cluster, page space, path, user 
catalog, data, and index. If a data or index component entry is to be 
altered, the master password of the cluster, component, or catalog can be 
supplied. For the following entry types, the password must be the update- 
or higher-level of the catalog that contains the entry: nonVSAM and GDG. 



ADDVOLUMES( volser [ h wiser ] ) 

specifies volumes to be added to the Ust of overflow (candidate) volumes. 

A volume serial number, volser, may contain one to six alphameric, 
national (@, #, and $), and special characters; the special characters 
include commas, blanks, semicolons, parentheses, slashes, asterisks, 
periods, quotation marks, ampersands, plus signs, hyphens, and equal signs. 
A volume serial number must be enclosed in single quotation marks if it 
contains a special character. Single quotation marks within a volume serial 
number must be coded as two single quotation marks. 

The vohimes to be added as candidate vclumcs iriust already be owacu by 
the catalog that contains the entry being altered; that is, space must have 
been defined on a volume to be added or the volume must have been, 
identified as a candidate volume. 

Abbreviation: AVOL 

ATTEMPTSC number ) 

specifies the maximum number of times the operator can try to enter a 
correct password in response to a prompting message. If is specified, the 
operator is not prompted and is not allowed to enter a password from the 
console. This parameter can be coded, but only has effect when the entry's 
master password is not null. A prompting message is issued only when the 
user has not already supplied the appropriate password. 

number 

is an integer from to 7 and can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n') form. 

Note to TSO usere: Ai a TSO terminal, the logon password is checked first 
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/ 



ALTER 

before the user is prompted to supply a password. Checking the logon 
password counts as one attempt to obtain a password. If ATTEMPTS is 
not specified, the user has one attempt to supply the password because the 
default is 2. 

Abbreviation: ATT 

AUTHORIZATION( entrypoint [b string]) 

specifies that a user-security-verification routine (USVR) is available for 
additional security verification, 

entrypoint 

specifies the name of the USVR. entrypoint can contain 1 to 8 
alphameric characters (A through Z, and through 9), or national 
characters (@,#,$), and special characters (the hyphen (-) and the 12-0 
overpunch (X'C)). The name's first character is either an alphabetic 
character or a national character. 

string 

specifies information to be passed on to the USVR when it receives 
control to verify authorization, string can contain 1 to 255 EBCDIC 
characters. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single quotation marks (for 
example, AUTHORIZATION(enr/y/>omf, '*DORIS*')). 

When the string contains a special character and also contains a 
Single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, AUTHORIZATION(enrr)pom/, 
'♦CA"ROL*')). 

You can code string in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
hlirnomZKriOHientrypoint, X'E2E4C5') is the same as 
KXJTBOmZKTKmientrypoint, SUE). The string can contain up to 255 
hexadecimal characters when expressed in this form, resulting in up to 
128 bytes of information. 

Abbreviation: AUTH 

BUFFERSPACE( size ) 

specifies the minimum space to be provided for buffers. The amount 
specified should be greater than or equal to the amount specified in the 
original definition. If the amount is less than was specified when the entry 
was defined, VSAM attempts to get enough space to contain two data 
component control intervals and, if the data is key sequenced, one index 
component control interval. BUFFERSPACE can be specified only for a 
catalog, or for a cluster's or alternate-index's data component. 

size 

is the amount of space to be provided for buffers. If you are altering the 
bufferspace for a catalog, the decimal values you can specify are limited 
to 3072, 4096, 5120, 6144, 7168, and 8192. 
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size can be expressed in decimal (n), hexadecimal (X'n'), or binary 
(B'n') form. If the size specified is less than the amount VSAM requires, 
VSAM gets the amount it requires when the data set is opened. 

Abbreviations: BUFSP or BUFSPC 

CATALOG( catname [/ password ] ) 

specifies the catalog location of the entry to be altered. See "Order of 
Catalog Use: ALTER" for information about the order in which catalogs 
are searched. 

catname 

specifies the name of the catalog that contains the entry. 

password 

specifies the master password of the catalog that contains the entry to 
be altered. If the entry to be altered is password protected and the 
catalog is also password protected, a password must be entered either 
through this parameter or through the parameter that specifies the entry 
to be altered. 

Abbreviation: CAT 

CODEC code ) 

specifies a code name for the entry being altered. If an attempt is made to 
access a password-protected entry without a password, the code name is 
used in a prompting message; the code enables the operator or TSO 
terminal user to be prompted for the password without disclosing the name 
of the entry. 

If CODE is not specified and an attempt is made to access a cluster or 
component that is password protected without supplying a password, the 
operator or TSO terminal user is prompted with the name of the entry. 

code 

can contain 1 to 8 EBCDIC characters. When the code contains a 
special character (that is, a conrnia [,], semicolon [;], blank [fe], period 
[.], single quote ['], ampersand [ & ], plus sign [+], equal sign [=], 
hyphen [-], parenthesis [(or )], slash [/], or asterisk [*], enclose the code 
in single-quotation marks (for example, CODEC*DORIS*'))- 

When the code contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, CODEC*CA"ROL*')). 

You can code code in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
CODE(X'E2E4C5') is the same as CODE(SUE). 

CONTROLPW( password ) 

specifies a control password for the entry being altered. 

password 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand 
[ & ], plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash 
[/], or asterisk [*], enclose the password in single quotation marks (for 
example, CONTROLPWC*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, CONTROLPWC*CA"ROL*')). 
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You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
CONTROLPW(X'E2E4C5') is the same as CONTROLPW(SUE). 

Abbreviation: CTLPW 

DESTAGEWAIT | NODESTAGEWATT 

specifies whether a data or index component that is stored on a 
mass-storage volume is to be destaged synchronously or asynchronously 
with respect to the program that closes it. These parameters can be 
specified only for the data or index component of a cluster or alternate 
index. 

DESTAGEWAIT indicates that destaging is to be completed before 
control is returned from VSAM to the program that issues the CLOSE 
macro. VSAM can thus notify the program whether destaging was 
successful. 

NODESTAGEWATT indicates that notification of unsuccessful destaging 
is to be made only by a message to the operator. 

Abbreviations: DSTGW and NDSTGW 

EMPTY I NOEMPTY 

specifies what is to happen when the maximum number of generation data 
sets has been cataloged. EMPTY specifies that all of the generation data 
sets are to be uncataloged. NOEMPTY specifies that only the oldest 
generation data set is to be uncataloged. 

Abbrevlatioiis: EMP and NEMP 

ERASE I NOERASE 

specifies whether the data component is to be erased when its entry in the 
catalog is deleted. If ERASE is specified, the component is overwritten 
with binary zeros when its catalog entry is deleted. 

Abbreviations: ERAS and NERAS 

EXCEPTIONEXTTC entrypoint ) 

specifies the name of the user-written routine that receives control when an 
exception (usually an I/O error) occurs while the entry's object is being 
processed. An exception is any condition that causes a SYNAD exit to be 
taken. The object's exception exit routine is processed first, then the user's 
SYNAD-exit routine receives control. 

You cannot specify this parameter to add an exception-exit routine to a 
VSAM cluster that is cataloged in a VSAM catalog created in an 
OS/VS2-2 (or lower release level) system. 

Abbreviation: EEXT 

FILE( dname ) 

specifies the name of a DD statement that describes the volume whose 
catalog recovery area contains the entry's copy. You can specify FILE when 
the entry to be altered is in a recoverable catalog. See the section "Restoring 
Catalog Entries After System Failure" for a description of catalog recovery 
area contents for each volume. The volume whose catalog recovery area 
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contains a copy of the catalog entry must always be identified in the DD 
statement referenced via FILE. In addition: 

• If you specify ADD VOLUMES or REMOVEVOLUMES, the volume (s) 
being added or removed must be identified. 

• If you specify NEWNAME for a nonVSAM data set or the data or index 
component of a unique cluster, alternate index, or page space which does 
not reside on the same volume as the catalog recovery area entry, that 
volume(s) must be identified. If FILE is not specified, the catalog recovery 
area volume (s) is dynamically allocated. It must be mounted as 
permanently resident or reserved. 

FILE can be used to specify the name of a DD statement that identifies the 
volume of an entry to be renamed if a nonVSAM data set or the data or 
index component of a unique cluster, alternate index, or page space is to be 
renamed. If FILE is not specified, the object's volume is dynamically 
allocated. The object's volume must be mounted as permanently resident 
or reserved. 

FILE can be used to identify the name of the partitioned data set if a 
member is to be renamed. If FILE is not specified, the partitioned data set 
is dynamically allocated. 

If multiple volumes of different device types are to be identified via FILE, 
you must use concatenated DD statements. 

FREESPACE( Cl-percent [b CA-percent ]) 

specifies the amount of space that is to be left free after any allocation and 
after any split of control intervals (Cl-percent) and control areas 
(CA-percent). 

The amounts are specified as percentages. The percentages, which must be 
equal to or less than 100, may be expressed in decimal, hexadecimal, or 
binary. If you specify 100 percent of free space, one record is placed in 
each control interval and one control interval is placed in each control area. 

Cl-percent and CA-percent can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n') form. 

Abbreviation: FSPC 

INHIBIT I UNINHIBIT 

specifies whether the entry being altered can be accessed for any operation 
or for only read operations. INHIBIT specifies that the entry being altered 
is only to be read. UNINHIBIT specifies that the read-only restriction set 
by a previous ALTER or EXPOR'l command is to be removed. 

Abbreviations: INH and UNINH 

KEYS( length h offset ) specifies the length and offset of the object's key. If 
the entry being altered defines an alternate index, offset applies to the 
alternate key in the data records in the base cluster. For more information, 
see entryname. 

Restrictions: Can be specified only if all of the following are true: 

• The object whose entry is being altered contains no data records. 

• The values for KEYS in the catalog must be default values. However, if 
nondefault keys are altered and the new value matches the old, 
processing continues for any other parameters specified on the 
command. For default values, see the DEFINE command that defines 

tUa. nU.ia.^4- 
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• The key must fit within the record whose length is specified by the 
RECORDSIZE parameter. 

• The key must fit in the first record segment of a spanned record. 

• The new values for KEYS must not conflict with the control interval 
size specified when the object was defined. 

• The object whose entry is being altered is an alternate index, a path, a 
key-sequenced cluster, or a data component of a key-sequenced cluster 
or alternate index. 

length h offset 

specifies the length of the key (between 1 and 255), in bytes, and its 
displacement from the beginning of the data record, in bytes. You can 
express length and offset in decimal (n), hexadecimal (X'n'), or binary 
(B'n') form. 

MASTERPWC password ) 

specifies a master password for the entry being altered. For more details 
about the object's master password, see the DEFINE command that 
defines the object. 

The AUTHORIZATION, CODE, and ATTEMPTS parameters have no 
effect unless the entry has a master password associated with it. If 
MASTERPW is not specified, the highest level password specified becomes 
the password for all higher levels. The MASTERPW is not specified, the 
highest level password specified becomes the password for all higher levels. 
The master password allows all operations. 

password 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*], enclose the password in single quotation marks (for 
example, MASTERPWC*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, MASTERPWC *CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 

MASTERPW(X'E2E4C5') is the same as MASTERPW(SUE). 

Abbreviation: MRPW 

NEWNAME( newname ) 

specifies that the entry to be altered is to be given a new name. 

The new name may contain 1 to 44 alphameric characters, (A through Z, 
and through 9), national characters ((§), #, and $), and two special 
characters (the hyphen and 12-0 overpunch). Names that contain more 
than eight characters must be segmented by periods; one to eight 
characters may be specified between periods. The first character of any 
name or name segment must be either an alphabetic character or a national 
character. 
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If the object being renamed is a unique cluster or component, or a 
nonVSAM data set, the object's volume must be mounted because the 
volume's VTOC is modified. You can use a JCL DD statement (see the 
FILE parameter) to cause the object's volume(s) to be allocated. If you do 
not supply a DD statement, the object's volume(s) is dynamically allocated. 
The volume (s) must be mounted as either permanently resident or 
reserved. 

If you specify generic names, you specify both the entryname and the 
newname as generic names. See "Generic Names and ALTER" for details 
on generic names. 

If yoq are renaming a member of a nonVSAM partitioned data set, the 
newname must be specified in the format: pdsname(membemame). 

If you are renaming a VSAM data set v/hich is RACF-protected, the 
existing RACE data set profile will be renamed. If a data set profile already 
exists for the new data set name prior to the ALTER command, the 
command is terminated and the data set name and/or protection attributes 
remain unchanged. If the old profile cannot be found or cannot be altered 
to the NEWNAME, the NEWNAME action wiU not be completed in the 
catalog, and an error message will indicate the reason for noncompletion. 

Abbreviation: NEWNM 

NULLIFY 

specifies that the protection attributes identified by subparameters of 
NULLIFY are to be nullified. Attributes are nulUfied before any 
respecification of attributes is performed. If all levels of passwords are 
nullified and none are respecified, CODE, AUTHORIZATION, and 
ATTEMPTS have no effect. 

Abbreviation: NULL 

AUTHORIZATION(MODULE | STRING) 

specifies that either the user-authorization routine or the user- 
authorization record is to be nullified. When MODULE is specified, the 
module name is removed from the catalog record, but the module itself 
is not deleted. If you nullify the user-authorization module, the 
user-authorization record (character string) is also nullified. When you 
nullify the authorization record, the corresponding module is not 
nullified. 

Abbreviations: AUTH, MDLE, and STRG 

CODE 

specifies that the code name used for prompting is to be nullified. 

CONTROLPW 

specifies that the control password is to be nullified. 

Abbreviation: CTLPW 

EXCEPnONEXn 

specifies that the entry's exception exit is to be nullified. The module 
name is removed from the catalog record, but the exception-exit 
routine itself is not deleted. 

Abbreviation: EEXT 
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MASTERPW 

specifies that the master password is to be nullified. K a new master 
password is not specified and if other passwords exist, the hi^est level 
password that exists automatically becomes the password for all higher 
levels, including the master. 

Abbreviation: MRPW 

OWNER 

specifies that the owner identification is to be nullified. 

READPW 

specifies that the read password is to be nullified. 

Abbreviation: RDPW 

RETENTION 

specifies that the retention period, specified in a TO or FOR parameter, 
is to be nullified. 

Abbreviation: RETN 

UPDATEPW 

specifies that the update password is to be nullified. 

Abbreviation: UPDPW 

OWNER( ownerid ) 

specifies the identification of the owner of the entry being altered. 

ownerid 

can contain 1 to 8 EBCDIC characters. When the ownerid contains'a 
special character (that is, a comma [,], semicolon [;], blank [b], period 
[.], single quote ['], ampersand [ & ], plus sign [+], equal sign [=], 
hyphen [-], parenthesis [( or )], slash [/], or asterisk [*], enclose the 
ownerid in single-quotation marks (for example, OWNERC*CA"ROL*')). 

When the ownerid contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, OWNERC*CA"ROL*')). 

You can code ownerid in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
OWNER(X*E2E4C5') is the same as OWNER(SUE). 

READPW( password ) 

specifies a read password for the entry being altered. 

password 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*], enclose the password in single quotation marks (for 
example, READPWC*DORIS*')). 
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When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, READPWC*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
READPW(X*E2E4C5') is the same as READPW(SUE). 

Abbreviation: RDPW 

RECORDSIZE( average h maximum ) 

specifies the new average and maximum lengths for the data records in the 
object. If the object whose entry is being altered is an alternate index path, 
the alternate index itself is altered; if the path points directly to its base 
cluster, then the base cluster is altered. If the object whose entry is being 
altered is an alternate index, the alternate key must be within the limit 
specified by maximum. For more information, see entryname. 

Restrictions: RECORDSIZE can be specified only if all of the following 
are true: 

• The object whose entry is being altered contains no data records. 

• The value for maximum RECORDSIZE in the catalog must be the 
default value. However, if a nondefault value is altered and the new 
value matches the old, processing continues for any other parameters 
specified on the conmiand. For default values, see the DEFINE 
command that defines the object. 

• The new maximum record length must be at least seven bytes less than 
control interval size, unless the record is a spanned record. 

• The new record length must be large enough to contain all prime and 
alternate keys previously defined. 

• For an alternate index, if NONUNIQUEKEY is specified, 
RECORDSIZE must account for the increased record size resulting 
from the multiple prime-key pointers in the alternate index data record. 

• The object whose entry is being altered is an alternate index, a cluster, a 
path, or a data component. 

Abbreviation: RECSZ 

REMOVEVOLUMES( wiser [ b volser] ) 

has two uses: (1) REMOVEVOLUMES specifies volume(s) to be removed 
from the list of candidate volumes associated with the entry being altered. 
Volumes specified are removed after any new volumes are added to the 
candidate list. If a volume to be removed contains data that belongs to the 
entry being altered, the volume is not removed. For this use of 
REMOVEVOLUMES, the name of the data or index component must be 
specified in the entryname parameter. (2) REMOVEVOLUMES specifies 
volume (s) from which all VSAM data spaces are to be removed and 
VSAM ownership is to be taken away — without access to the user catalog 
that owns the volume(s). For this use of REMOVEVOLUMES, the name 
of the master catalog and its master password (if any) must be specified in 
the entryname parameter, and the FILE parameter is required. (You can 
have only one DD statement with this use of ALTER 
REMOVEVOLUMES — only volumes of the same device type can be 
processed.) See the section "VSAM Volume Cleanup" in the chapter 
"Data Security and Protection" and the section "VSAM Volume Recovery 
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Function" in the chapter "Modifying Catalog Information" for information 
I and cautions about this use of ALTER REMOVEVOLUMES. 

A volume serial number, volser, may contain one to six alphameric, 
national (@, #, and $), and special characters; the special characters 
include commas, blanks, semicolons, parentheses, slashes, asterisks, 
periods, quotation marks, ampersands, plus signs, hyphens, and equal signs. 
A volume serial number must be enclosed in single quotation marks if it 
contains a special character. Single quotation marks within a volume serial 
number must be coded as two single quotation marks. 

Abbremtion: RVOL 

SCRATCH I NOSCRATCH 

specifies whether generation data sets are to be removed from the VTOC 
of the volume on which they reside when they are uncataloged (that is, 
whether the data set's format- 1 DSCB is removed — scratched — ^from the 
VTOC so that the data set can no longer be accessed). 

Abbreviations: SCR and NSCR 

SHAREOPTIONSC crossregion [b crosssystem ] ) 

specifies how a data or index component of a cluster or alternate index can 
be shared among users (see OS/VJS Virtual Storage Access Method (VSAM) 
Programmer's Guide for a full description of data set sharing). This 
parameter can be specified only for the data or index components of 
clusters and alternate indexes. 

crossregion 

specifies the amount of sharing allowed among regions (within the same 
\ system). Independent job steps in an operating system can access a 

VSAM data set concurrently. To share a data set, each user must specify 
DISP=SHR in the data set's DD statement. The values that can be 
specified are: 

1 

specifies that the data set can be shared by any number of users for 
read processing, or the data set can be accessed by only one user for 
read and write processing. With this option, VSAM ensures complete 
data integrity for the data set. 

2 

specifies that the data set can be accessed by any number of users for 
read processing and it can also be accessed by one user for write 
processing. With this option, VSAM ensures write integrity by 
obtaining exclusive control for a control interval when it is to be 
updated. If a user desires read integrity, it is his responsibility to use 
the ENQ and DEQ macros appropriately to provide read integrity for 
the data his program obtains. 

3 

specifies that the data set can be fully shared by any number of users. 
With this option, each user is responsible for maintaining both read 
and write integrity for the data his program accesses. User programs 
that ignore the write integrity guidelines can cause VSAM program 
checks, lost or inaccessible records, uncorrectable data set failures, 
and other unpredictable results. This option places heavy 

\ responsibility on each user sharing the data set, 

/ 
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4 

specifies tliat the data set can be fully shared by any number of users 
and buffers used for direct processing are refreshed for each request. 
This option requires your program to use the ENQ and DEQ macros 
to maintain data integrity while sharing the data set. Improper use of 
the ENQ macro can cause problems similar to those described under 
SHAREOPTION 3. 

crosssystem 

specifies the amount of sharing allowed among systems. Job steps of 
two or more OS/VS operating systems can gain access to the same 
ySAM data set regardless of the disposition specified in each step's DD 
statement for the data set. To get exclusive control of the data set's 
volume, a task in one system issues the RESERVE macro. The level of 
cross-system sharing allowed by VSAM applies only in a multiple 
operating system environment. The values that can be specified are: 

1 

Reserved 

2 

Reserved 

3 

specifies that the data set can be fully shared. With this option, each 
user is responsible for maintaining both read and write integrity for 
the data his program accesses. User programs that ignore 
write-integrity guidelines can cause VSAM program checks, 
uncorrectable data set failures, and other unpredictable results. This 
option places heavy responsibility on each user sharing the data set. 

4 

specifies that the data set can be fully shared. Buffers used for direct 
processing are refreshed for each request. This option requires that 
you use the RESERVE and RELEASE macros to maintain data 
integrity while sharing the data set. Writing is limited to PUT-update 
and PUT-insert processing that does not change the high-used RBA 
if your program opens the data set with DISP=SHR. Data set 
integrity cannot be maintained unless all jobs accessing the data set in 
a cross-system environment specify DISP=SHR. Improper use of the 
RESERVE macro can cause problems similar to those described 
under SHAREOPTION 3. 

Abbreviation: SHR 

STAGE I BIND | CYLINDERFAULT 

specifies how a data or index component that is stored on a mass-storage 
volume is to be staged. These parameters can be specified only for the data 
or index component of a cluster or alternate index. 

STAGE 

indicates that the component is to be staged from mass storage to a 
direct access storage staging drive when the component is opened. 

BIND 

indicates that the component is not only to be staged, but also to be 
bound- — that is, retained on the direct access storage staging drive until 
it is closed. 
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CYLINDERFAULT 

indicates that the component is not to be staged when it is opened, but 
that data from it is to be staged as a processing program needs it. 

Abbreviation: CYLF 

TO( date ) | FOR( days ) 

specifies the retention period for the entry being altered. This cannot be 
specified for the data or index components of clusters, alternate indexes, or 
catalogs. 

TO( date ) 

specifies the date, in the form yyddd, where yy is the year and ddd is the 
number (001 through 365) of the day, through which the entry is to be 
kept. 

FOR( days ) 

specifies the number of days for which the entry is to be kept. The 
maximum number that can be specified is 9999. If the number specified 
is through 1830, the cluster is retained for the number of days 
specified; if the number is between 1831 and 9999, the cluster is 
retained through the year 1999. 

days 

can be expressed in decimal (n), hexadecimal (X'n'), or binary (B'n') 
form. 

UNIQUEKEY | NONUNIQUEKEY 

specifies whether the alternate-key value can be found in more than one of 
the base cluster's data records. UNIQUEKEY specifies that each 
alternate-key value is unique. If the same alternate-key value is found in 
more than one of the base cluster's data records, an error results. 

NONUNIQUEKEY allows you to have an alternate-index record that, for 
a given alternate-key value, might point to more than one data record in 
the cluster. 

UNIQUEKEY can be specified only for an empty alternate index (that is, 
an alternate index that is defined but not yet built). 

NONUNIQUEKEY can be specified for an alternate index at any time. If 
the alternate index is empty, you should also consider specifying 
RECORDSIZE to ensure that each alternate index record is large enough 
to contain more than one data record pointer. 

Abbreviations: UNQK and NUNQK 

UPDATE 1 NOUPDATE 

specifies whether a base-cluster's alternate-index upgrade set is to be 
allocated when the path's name is allocated with a DD statement. 

• NOUPDATE specifies that the path's cluster is to be allocated, but that the 
cluster's alternate-index upgrade set is not to be allocated. 

Abbreviations: UPD and NUPD 
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UPDATEPW( password ) 

specifies an update password for the entry being altered. 

password 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], plus 
sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], or 
asterisk [*], enclose the password in single quotation marks 
(for example, UPDATEPW('*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, UPDATEPWC*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
UPDATEPW(X'E2E4C5') is the same as UPDATEPW(SUE). 

Abbreviation: UPDPW 

UPGRADE I NOUPGRADE 

specifies whether an alternate index is to be upgraded (that is, kept up to 
date) when its base cluster is modified. UPGRADE specifies that when the 
cluster's records are added to, updated, or erased, the cluster's alternate 
index is upgraded to reflect the changed data. 

If UPGRADE is specified when the cluster is open, the upgrade attribute 
does not apply to the alternate index until the cluster is closed and next 
opened (that is, a new set of VSAM control blocks describes the cluster 
and its attributes). 

UPGRADE can be specified only for an empty alternate index (that is, an 
alternate index that is defined but not built). However, the UPGRADE 
attribute is not effective for the alternate index until the alternate index is 
built (see the BLDINDEX command). 

NOUPGRADE can be specified for an alternate index at any time. 

Abbreviations: UPG and NUPG 

WRITECHECK | NOWRITECHECK 

specifies whether a data or index component is to be checked by a machine 
action called write-check when a record is written into it. If 
WRITECHECK is specified, a record is written and then read, without 
data transfer, to test for the data-check condition. 

Abbreviations: WCK and NWCK 
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ALTER Examples 

Alter a Cluster's Entry: Example 1 



In this example, an ALTER command is used to specify passwords for a 
nonindexed (entry-sequenced) cluster, D50.EXAMPLE.ESDS1. No password 
for the cluster is required, because the cluster was defined without passwords. 

//ALTER 1 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
ALTER - 

D50. EXAMPLE. ESDS1 - 

MASTERPW(DEPT26M) - 

CONTROLPWC DEPT26C ) - 

UPDATEPW{DEPT26U) - 

READPW( DEPT26R ) - 

AUTHORIZATION! D26AUTH ) 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The ALTER command adds passwords to the entry-sequenced cluster's 
cluster catalog entry. The passwords are not added to the cluster's data entry, 
however. If a user's program supplies the cluster's data entry entryname and 
opens the data component, the unauthorized user can access the cluster's data 
records even though the cluster itself is password protected. The ALTER 
command's parameters are: 

• D50.EXAMPLE.ESDS1, the name of the entry-sequenced cluster. It is 
assumed that an alias entry exists named D50 for the user catalog 
D27UCAT2. The data set name, D50.EXAMPLE.ESDS1, causes the 
ALTER request to be directed to D27UCAT2. 

. MASTERPW, CONTROLPW, UPDATEPW, READPW, and 

AUTHORIZATION, which specify passwords and the entryname of the 
user's-security-verification routine. 



Alter the Entrynames of GenericaUy Named Clusters: Example 2 



In this example, several clusters with similar names, GENERIC*. BAKER 
(where "*" is any 1 to 8 character simple name), are renamed so that their 
entrynames are GENERIC*. ABLE. The name "GENERIC. *.BAKER" is 
called a generic name. 

//ALTER2 JOB 

//JOBCAT DD DSNAME=D27UCAT1,DISP=SHR 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
ALTER - 

GENERIC*. BAKER - 

NEWNAME( GENERIC . * . ABLE ) 
/* 
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The job control language statements are: 

• JOBCAT DD, which makes a catalog avaUable for this job: D27UCAT1. 

• SYSPRINT DD, which is required in all Acess Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The ALTER command changes each generic entryname, 
GENERIC. *.BAKER, to GENERIC*. ABLE. Its parameters are: 

• GENERIC*. BAKER, which identifies the objects to be modified. 

• NEWNAME, which specifies that each generic entryname 
GENERIC.*.BAKER is changed to GENERIC*. ABLE. 



Alter the Attributes of a Generation Data Group: Example 3 



In this example, the attributes of a generation data group are modified. 
Because the attributes of the group are cataloged in the generation data 
group's base catalog entry, only this entry is modified. 

//ALTERS JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
ALTER - 

GDG01 - 

NOEMPTY - 

SCRATCH 
/* 

The job control language statements are: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The ALTER command modifies some of the attributes of generation data 
group GDGOl. Its parameters are: 

• GDGOl, which identifies the object to be modified. 

• NOEMPTY, which specifies that only the oldest generation data set is to 
be uncataloged when the maximum number of cataloged generation data 
S6ts is sxcssdsd. 



• SCRATCH, which specifies that the generation data set's DSCB is to be 
removed from the volume's VTOC when the data set is uncataloged. 

The attributes specified for the generation data group with the ALTER 
command override any attributes previously specified for the GDG. 
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BLDINDEX 



BLDINDEX 



BLDINDEX Parameters 
Required Parameters 






The format of the BLDINDEX command is: 



BLDINDEX 



{lN¥VLEidname{/ password]) \ 

IND ATASET( entryname [/password ]) } 
{ OUTFTLEC dname [/password ] 

[ b dname [/password ]...]) | 

OUTDATASETC entryname [/password ] 
[ b entryname [/password ]...])} 
[CATALOGC catname [/password ])] 
[EXTERNALSORT | INTERNALSORT ] 
[WORKFILES(f/wame b dname)] 



BLDINDEX can be abbreviated: BIX 



INFILE( dname [ / password ] ) 

names the DD statement that identifies the base cluster or a path that 
points to the base cluster. If the base cluster or path is password protected, 
you can supply the read (or higher-level) password of the object named in 
the DD statement. Otherwise, the operator or TSO terminal user is 
prompted to supply the correct password. 

The base cluster must be defined in the same catalog as the alternate index, 
and must contain data records. 

The alternate index identified with OUTDATASET or OUTFILE must be 
related to the base cluster. 

Abbreviation: IFBLE 

INDATASEK entryname [ / password ] ) 

names a base cluster or a path that points to the base cluster. If the base 
cluster or path is password protected, you supply the read (or higher-level) 
password of the named object. Otherwise, the operator or TSO terminal 
user is prompted to supply the correct password. When you specify 
INDATASET, the base-cluster's volume is dynamically allocated. 
Therefore, the base-cluster's volume must be mounted as permanently 
resident or reserved. 

The base cluster must be defined in the same catalog as the alternate index, 
and must contain at least one data record. 

The alternate index identified with OUTDATASET or OUTFILE must be 
related to the base cluster. 

Abbreviation: IDS 
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Optional Parameters 



OUTFILE( dname [ / password ] [ fe dname [ / password ] ..,] ) 

names the DD statement that identifies the alternate index or a path that 
points to the alternate index. You can build more than one alternate index 
for the same base cluster by specifying more than one dname with the 
OUTFILE parameter. If the alternate index or path is password protected, 
you can supply the update- (or higher-level) password of the object named 
in the DD statement. Otherwise, the operator or TSO terminal user is 
prompted to supply the correct password. 

The alternate index must be defined in the same catalog as the base cluster, 
and must be empty (that is, its high-used RBA equals zero) or defined with 
the reusable attribute. 

The alternate index must be related to the base cluster identified with 
INDATASET or INFILE. 

Abbreviation: OFILE 

OUTDATASET( entryname [ / password ] 

[ b entryname [ / password ]...]) 

names the alternate index or a path that points to the alternate index. You 
can build more than one alternate index for the same base cluster by 
specifying more than one entryname with the OUTDATASET parameter. 
If the alternate index or path is password protected, you supply the update 
(or higher-level) password of the named object. Otherwise, the operator or 
TSO terminal user is prompted to supply the correct password. When you 
specify OUTDATASET, the alternate-index's volume is dynamically 
allocated. Therefore, the volume must be mounted as permanently resident 
or reserved. 

The alternate index must be defined in the same catalog as the base cluster, 
and must be empty (that is, its high-used RBA equals zero) or must have 
been defined with the REUSE attribute. 

The alternate index must be related to the base cluster identified with 
INDATASET or INFILE. 

Abbreviation: ODS 



CaTALOG( catname [ / password j ) 

names the catalog that the workfiles are to be defined in. The workfiles are 
defined and used by the BLDINDEX routine. When aU alternate indexes 
are built and the workfUes are no longer needed by the BLDINDEX 
routine, they are deleted. 

password 

If the catalog is password protected, you can supply its update- (or 
higher-level) password. Otherwise, the operator is prompted to supply 
the correct password. 

See "Order of Catalog Use: BLDINDEX" for information about the order 
in which a catalog is selected when the CATALOG parameter is not 
specified. 

Abbreviation: CAT 
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BLDINDEX 

EXTERNALSORT | INTERNALSORT 

specifies whether the key-pointer pairs are to be sorted entirely within 
virtual storage. 

When you specify EXTERNALSORT, two external-sort workfiles are 
defined and built as VSAM entry-sequenced clusters. 

When you specify INTERNALSORT, or allow it to default, Access 
Method Services sorts the key-pointer pairs entirely within the 
user-provided virtual storage if possible. If not enough virtual storage is 
provided for an internal sort, two external sort workfiles are built and the 
key-pointer pairs are sorted externally. If the minimum amount of virtual 
storage is not provided (see "How an Alternate Index is Built") » the 
BLDINDEX processing terminates with an error message. 

When you specify EXTERNALSORT, or if not enough virtual storage is 
provided for an internal sort, you must provide two DD statements that 
describe the external-sort workfiles to be defined by BLDINDEX. 

You can name the DD statements IDCUTl and IDCUT2. When you 
choose other names for the workfile DD statements, you must identify the 
DD statements with the WORKFILES parameter. 

Abbremtions; ESORT and ISORT 

WORKFILES( dname h dname ) 

names the DD statements that identify the workfiles you want 
BLDINDEX to define if an external sort of the key-pointer pairs is 
required. You can use DD statements to describe two workfiles that will be 
defined and opened before the BLDINDEX routine begins processing the 
base-cluster's data records. 

When you code the DD statements that describe the workfiles and identify 
them with the standard dnames IDCUTl and IDCUT2, you do not need to 
specify the WORKFILES parameter. 

For information on how to code the DD statements that describe the 
workfiles, see "DD Statements that Describe the SORT Workfiles." 

Abbreviation: WFILE 
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BLDINDEX Example 



This example builds an alternate index over a previously-defined base cluster, 
EXAMPLE.KSDS2. Data records have aheady been loaded into the base 
cluster, so that it is not empty. The alternate index, its path, and its base 
cluster are all defined in the same catalog, AMASTCAT. 

//BUILDAIX JOB . . . 

//STEP1 EXEC PGM=IDCAMS 

//BASEDD DD DSNAME=EXAMPLE. KSDS2 ,DISP=OLD 

//AIXDD DD DSNAME=EXAMPLE.AIX,DISP=OLD 

//IDCUT1 DD DSNAME=SORT. WORK. ONE, DI SP=OLD, AMP= ' AMORG ' , 

// VOL=SER=VSER01 ,UNIT=2314 

//IDCUT2 DD DSNAME=SORT. WORK. TWO, DI SP=OLD, AMP= ' AMORG ' , 

// VOL=SER=VSER0 1 , UNIT=23 1 4 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

BLDINDEX INFILE( BASEDD) - 

OUTFILE(AIXDD/AIXUPPW) - 
CATALOG ( AMASTCAT/MCATUPPW ) 

/* 

The job control language statements are: 

• BASEDD DD, which describes the base cluster. 

• AIXDD DD, which describes the alternate index. 

. IDCUTl and IDCUT2 DD, which describe a volume containing VSAM 
data space to be made available to BLDINDEX for defining and using two 
sort work data sets in the event an external sort is performed. This data 
space will not be used by BLDINDEX if enough virtual storage is available 
to perform an internal sort. 

The BLDINDEX command builds an alternate index. The assumption is made 
that enough virtual storage will be available to perform an internal sort. 
However, note that DD statements with the default dnames of IDCUTl and 
IDCUT2 have been provided for two external sort work data sets in the event 
that the assumption is incorrect and an external sort must be performed. The 
BLDINDEX command's parameters are: 

• INFILE, which names the base cluster. The dname of the DD statement 
for this object must be identical to this name. Note that a password is not 
required since the base cluster is not protected. 

• OUTFILE, which names the alternate index. The dname of the DD 
statement for this object must be identical to this name. The update 
password of the alternate index is also required. 

• CATALOG, which identifies the master catalog. If it is necessary for 
BLDINDEX to use external sort work data sets, they will be defined in and 
deleted from the master catalog. The update password will permit these 
actions. 
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CHKLIST 



CHKLIST Parameters 
Required Parameter 



Optional Parameters 



The format of the CHKLIST command is: 



CHKLIST 



INFILEC ^name) 

[CHECKIDCc/iecfcuf...)] 

[OUTFILE(f/name)] 



CHKLIST can be abbreviated: CKXST. 



INHLEC dname ) 

specifies the name of the DD statement that identifies the checkpoint data 
set that contains the checkpoint entries to be processed. 

Abbreviation: IFILE 



CHECKID( checkid ... ) 

specifies one or more checkpoint identifiers of entries in the checkpoint 
data set for which to list tape data sets that were open at the time of the 
checkpoint. Each checkid must be one to sixteen characters in length. It 
must be enclosed in sin^e quotation marks if it contains commas, 
semicolons, blanks, parentheses, slashes, or asterisks. The checkid must be 
the same as was specified in the CHKPT macro. A maximum of 255 
checkids can be specified. Multiple checkid^ may be specified in any 
sequence. 

If CHECKID is omitted, identification of tape data sets that were open at 
the time of a checkpoint are listed for all entries in the checkpoint data set. 
CHECKID must be omitted when a member of a partitioned checkpoint 
data set has been specified after dsname in the DD statement identified by 
INFILE. 

If the checkpoint data set contains dupUcates of a checkid, you can cause 
all of the checkpoint entries with that checkid to be listed either by 
specifying the checkid at least twice or by specifying, along with the 
checkid, a checkid for which there is no entry in the checkpoint data set. 
If you do neither, only the fkst checkpoint entry found with the checkid is 
listed. 

Abbreviation: CHKID 

OUTFILE( dname ) 

specifies the ddname of the DD statement that identifies a data set other 
than the SYSPRINT data set to be used as an output data set. An output 
data set must meet the requirements shown under "Output Data Sets" in 
the "Introduction." If OUTFILE is not specified, the tape data set 
information is listed in the SYSPRINT data set. 

Abbreviation: OFILE 
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CHKLIST Examples 

Selecting Specific Checkpoint Entries: Example 1 



In this example, the tape data sets that were open at checkpoint time are 
identified and listed on SYSPRINT for checkpoint entries COOOOOOl and 
C0000002. 

//CHKLIST 1 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 

//CHKPT DD DSN=CHKPT.DATASET,DISP=OLD 
//SYSIN DD * 
CHKLIST ~ 

INFILE( CHKPT) - 
CHECKID( COOOOOOl C0000002 ) 
/* 

The job control statements are: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are sent. 

• CHKPT DD, which identifies the checkpoint data set that contains the 
entries for which the tape data set information is to be listed. 

The CHKLIST command prints the tape data set information as specified by 
the command's parameters: 

. INFILE, which points to the CHKPT DD statement. The CHKPT DD 
statement identifies the checkpoint data set. 

• CHECKID, which specifies that the checkpoint entries with checkids 
COOOOOOl and C0000002 are the only ones on the checkpoint data set for 
which the tape data set information is to be listed. 

The output shown in "Appendix E: Sample Output From CHICLIST" was 
obtained with this JCL. 



Partitioned Checkpoint Data Set: Example 2 



In this example, the checkpoint data set is a partitioned data set, and member 
COOOOOOl is selected for processing by CHKLIST. 



//CHKLiST2 JOB 


. . . 


//STEP1 EXEC 


PGM=IDCAMS 


//SYSPRINT DD 


SYSOUT=A 


//CHKPTDD DD 


DSN=EXAMPLE . CHKPTDS2 ( COOOOOO 1 ) , 


// DISP=SHR 




//SYSIN DD 


* 


CHKLIST - 




INFILE (CHKPTDD) 


/* 





The job control language statements are: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

• CHKPTDD DD, which identifies the partitioned checkpoint data set and 
the specific member for which the tape data set information is to be listed. 

The CHKLIST command prints the tape data set information as specified by 
its parameter, INFILE, which points to the CHKPTDD DD statement. The 
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CHKLIST 



CHKPTDD DD statement identifies the member of the partitioned 
checkpoint data set. 

Note: The CHECKID parameter is omitted so that the checkpoint entry 
COOOOOOl will automatically be processed by CHKLIST. 



Corr 



CNVTCAT 



CNVTCAT 



CNVTCAT Parameters 

Required Parameters 



Optional Parameters 



\ 



The format of the CNVTCAT command is: 



CNVTCAT 



{INFILE( ^/wme) I INDATASETC enfryname)} 
[CATALOG( catmme [/password ])] 
[CVOLEQUATES(( catname b ( volser 

[b volser ...'\))\h{catname ...)...])\ 
[ LIST I NOLIST] 
[MASTERCATALOGC catname {/password ])] 



CNVTCAT can be abbreviated: CNVTC 



INFILE( dname ) 

specifies the name of a DD statement that identifies the OS catalog that is 
to be converted. 

Abbreviation: IFILE 

INDATASETC entryname ) 

specifies the control-volume-pointer (CVPE) name (not the data set name) 
of the OS catalog that is to be converted. If INDATASET is specified, the 
OS catalog is dynamically allocated. The OS system catalog entryname, 
SYSCTLG, cannot be specified. If entries in the system catalog are being 
converted, INFILE must be used to specify a DD statement that identifies 
the OS system catalog. 

Abbreviation: IDS 



CATALOG( catname [ / password ] ) 

specifies the name of a catalog that is to receive the converted entries. If 
CATALOG is not specified, see "Order of Catalog Use: CNVTCAT" for 
information about the order in which a catalog is selected. 

password 

specifies, for a passv^^ord-protected catalog, the update- or higher-level 
password. 

Abbreviation: CAT 
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CVOLEQUATES(( catname b ( wiser [ b volser ... ] ))[b( catname.,.)] 
identifies the user catalog that converted control-volume-pointer entries 
(CVPEs) point to. CVPEs point to control volumes (CVOLs) which 
contain OS catalog entries. The OS catalog entries in a CVOL might have 
been (or might soon be) converted to VSAM catalog entries and put into a 
user catalog. When a CVPE is converted to an alias entry, the alias entry 
points to the user catalog that contains (or is to contain) the control 
volume's converted OS catalog entries. 

When you specify CVOLEQUATES, you must also specify 
MASTERCATALOG. 

catnarm 

specifies the name of an existing VSAM catalog. The catalog named 
contains or is to contain converted OS catalog entries that were 
cataloged in the CVOL pointed to by the CVPE being converted. 

volser 

specifies the volume serial number(s) of one or more CVOLS for which 
entries have been or are to be converted. 

Abbreviation: CVEQU 

LIST I NOLIST 

specifies whether entries are to be listed after they are converted. 

Abbreviation: NLST 

MASTERCATALOGC catname [ / password ] ) 

specifies the name of the master catalog into which any aliases for user 
catalogs are to be placed. MASTERCATALOG is required when 
CVOLEQUATES is specified. 

password 

specifies the master catalog's update- or higher-level password. 

Abbreviation: MCAT 
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CNVTCAT 



The two CNVTCAT examples are related and show how the entries of two 
catalogs in an OS system can be converted to entries in a VSAM catalog. The 
catalog on volume VSER09 contains control- volume-pointer entries (CVPEs) 
that point to the catalog on volume VSER08. Therefore, the two catalogs are 
chained together with VSEROS's catalog at the end of the chain. When two or 
more OS catalogs are chained together, the catalog at the end of the chain 
should be converted first. 



Convert an OS Catalf^*s Entries to Entries in a VSAM Catalog: Example 1 



In this example, the entries in the catalog on volume VSER08 are converted 
to VSAM catalog entries and written into the USERl 1 catalog. 

//CNVTCAT 1 JOB 
//STEP! EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 

//0SCAT1 DD VOL=SER=VSER08,DISP=OLD,DSN=SYSCTLG, 
// UNIT=2314 
//SYSIN DD * 
CNVTCAT - 

INFILE(0SCAT1 ) - 

CATALOG! USERl 1 /MR ) 
/* 

The job control language statements are: 

• OSCATl DD, which describes and allocates the OS catalog that is to be 
converted. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which' Access 
Method Services messages to the programmer are to be sent. 

The CNVTCAT command converts the entries in the OS catalog on volume 
VSER08 to entries in a user catalog, USERl 1. The command's parameters 
are: 

. INFILE, which points to the OSCATl DD statement. The OSCATl DD 
statement describes and allocates the OS catalog that is to be converted. 

• CATALOG, which specifies the name of an existing VSAM catalog, the 
user catalog USERl 1. USERl 1 is to receive the converted entries. The 
user catalog's update- (or higher-level) password, MR, is required. 
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Convert an OS Catalog's Entries to Entries in a VSAM Catalog: Example 2 



In this example, the entries in the OS catalog on volume VSER09 are 
converted to VSAM catalog entries and written into the USER 12 catalog. 
Some of the entries in the OS catalog are control volume pointer entries, and 
point to the OS catalog on volume VSER08 (which was converted in the 
previous example). 

//CNVTCAT2 JOB 
//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//0SCAT2 DD VOL=SER=VSER09,DISP=OLD,DSN=SYSCTLG, 

// UNIT=2314 
//SYSIN DD * 

CNVTCAT - 

INFILE(0SCAT2 ) - 

CATALOG ( USER1 2/MR ) - 

CVOLEQUATES( - 

(USER1 1 (VSER08) ) ) - 

NOLIST - 

MASTERCATALOG( AMASTCAT ) 
/* 

The job control language statements are: 

• OSCAT2 DD, which describes and allocates the OS catalog that is to be 
converted. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The CNVTCAT command converts the entries in the OS catalog on volume 
VSER09 to entries in a user catalog, USER 12. Because CVOLEQUATES is 
specified, an alias entry is buUt and put in the master catalog to relate the 
name VSER08 to the user catalog USERl 1. The command's parameters are: 

. INFILE, which points to the OSCAT2 DD statement. The OSCAT2 DD 
statement describes and allocates the OS catalog to be converted. 

• CATALOG, which specifies the name of an existing VSAM catalog, the 
user catalog USER 12. USER 12 is to receive the converted entries. The 
user catalog's update- (or higher-level) password, MR, is required. 

c CVOLEQUATES, which specifies that control-volume-pointer entries 
(CVPEs) are to be converted to aUas entries. Each CVPE in VSER09's 
catalog points to an entry in VSEROS's catalog. Each new aUas entry 
points to the USERl 1 user catalog connector entry in the master catalog. 
The alias entries are written into the master catalog. 

e NOLIST, which specifies that the entries are not to be listed after they are 
converted. 

• MASTERCATALOG, which identifies the master catalog. This parameter 
must be specified because CVOLEQUATES is also specified. If the master 
catalog is password protected, the catalog's update- (or higher-level) 
password must be specified. 
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DEFINE ALIAS 



The format of the DEFINE command when it is used to define an alias is: 



DEFINE 



ALIAS 

(N AME( aliasname ) 
RELATEC entryname ) ) 
{CkTMjOG(catname {/ password\)\ 



DEFINE may be abbreviated: DEF. 



DEFINE ALIAS Parameters 
Required Parameters 



Optional Parameter 



ALIAS 

specifies that an alias for a user catalog or nonVSAM data set is to be 
defined. 

NAME( aliasname ) 

specifies the alias — the alternate entryname for a user catalog or 
nonVSAM data set. 

aliasname can contain 1 to 44 alphameric characters (A through Z, and 
through 9), national characters (@, #, and $), and special characters (the 
hyphen (-), and the 12-0 overpunch (X'CO')). 

When the name contains more than eight characters, you divide the name 
into segments of 1 to 8 characters each and separate the segments with (.) 
periods. 

The name's first character (and each segment's first character) is either an 
alphabetic character or a national character. 

RELATE( entryname ) 

specifies the name of the entry (that is, the user-catalog entryname or the 
nonVSAM data set name) for which the alias is being defined. 

An alias entry must reside in the same catalog as the entry to which it is 
related. When an alias is defined, catalogs are searched for the related 
entry. When the related entry is found, the alias entry is added to the 
catalog. An alias must be unique within a catalog. An alias can be defined 
only for a nonVSAM data set or for a user-catalog connector in the master 
catalog. 

Abbreviation: REL 



CATALOG( catname [/ password ]) 

identifies the catalog in which the alias is to be defined. If the catalog's 
volume is physically mounted, it is dynamically allocated. The volume must 
be mounted as permanently resident or reserved. See "Order of Catalog 
Search: DEFINE" for information about the order in which a catalog is 
selected when the catalog's name is not specified. 
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catname 

specifies the name of the catalog. When the alias is for a user catalog 
connector, catname is the name of the master catalog. 

password 

specifies a password. If the catalog is password protected, you must 
supply the catalog's update- or higher-level password. If no password is 
specified and the catalog is password protected, VSAM asks the 
operator or TSO terminal user for the correct password. 

Abbreviation: CAT 
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DEHNE AUAS Examples 

Define an Alias for a NonVSAM Data Set: Example 1 

In this example, an alias is defined for a nonVSAM data set. 

//DEFALS JOB 
//STEP1 EXEC PGM=iDCAMS 
//STEPCAT DD DSNAME=D27UCAT1 ,DISP=OLD 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DEFINE ALIAS - 

( NAME( EXAMPLE .NONVSAM 1 ) - 
RELATE ( EXAMPLE . NONVSAM ) ) 
/* 

The job control language statements are: 

• STEPCAT DD, which makes a catalog available for this job step: 
D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DEFINE ALIAS command defines an alias, EXAMPLE.NONVSAMl, 
for the nonVSAM data set EXAMPLE.NONVSAM. Its parameters are: 

• NAME, which specifies the alias (alternate entryname), 
EXAMPLE.NONVSAM1. 

• RELATE, which specifies the name that the alias is an alternate entryname 
for, EXAMPLE.NONVSAM. 

Define an Alias for a User Catalog: Example 2 



In this example, an alias is defined for a user catalog. The alias is defined in 
the master catalog. 

//DEFUCALS JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DEFINE ALIAS - 

(NAME(D40) - 

RELATE! D27UCAT1 ) ) - 

CATALOG ( AMASTCAT/MCATUPPW ) 
/* 

The job control statements are: 

• SYSPRINT, which is required in all Access Method Services job steps. The 
SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 
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The DEFINE ALIAS command defines an alias, D40, for the VSAM user 
catalog, D27UCAT1. Any data set defined in D27UCAT1 havuig 'D40' as its 
first qualifier will be located by VSAM in D27UCAT1 when it is referenced 
in an Access Method Services command or user program without requiring a 
JOBCAT or STEPCAT DD statement for D27UCAT1. D27UCAT1 can also 
be referenced using the alias D40. The parameters are: 

• NAME, which specifies the alias, D40. 

• RELATE, which specifies the name of the user catalog for which D40 is an 
alternate entryname (alias). 

• CATALOG, which supplies the update password of the master catalog. 
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DEFINE ALTERNATEINDEX 

When you define an alternate index, you can specify attributes for the 
alternate index as a whole and for the alternate-index's components. The 
format of the DEFINE ALTERNATEINDEX command is: 

DEFINE ALTERNATEINDEX (parameters) - 

[DATA(parameters)] - 

[INDEX(parameters)] - 

[CATALOG(subparameters)] 
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DEFINE ALTERNATEINDEX 



DEFINE 



ALTERNATEINDEX 

(N AME( entryname ) 

RELATEC entryname {/password ]) 

{CYUNDEMSi^pnmaryVbsecondary]) \ 

RECORDS(/?rimarK[b secondary'\) \ 

TRACKSCpnmary [ b secondary ])} 
VOLUMES(vo/ser[b vo/ser...]) 
[ATTEMPTS( number |2)] 
[AUTHORIZATION( enfrKpomr [b 5/rmg ])] 
[BUFFERSPACE(5ize )] 
[CODEC c«fe)] 

[CONTROLINTERVALSIZEC 5ize )] 
[CONTROLPW(/?a*5wor<^ )] 
[DESTAGEWATT | NODESTAGEWATT ] 
[ERASEI NOERASE ] 
[EXCEPTIONEXrrC enrrypomf )] 
[FILECd'rwme)] 

[FREESPACEC CI-percent{h CA-percent ] I 0)] 
[IMBED 1 NOIMBED ] 
[KEYRANGES((towikeK b highkey) 

[ lowkey b highkey )...])] 
[KEYSC/engr/i h offset \ 64 0)] 
[MASTERPW(pa*5wor(f )] 
[MODELientryname [/password ] 

[hcatname [/password ]])] 
[ORDERED I UNORDERED ] 
[OWNERiownerid)] 
[VtEADVViipassword}] 
[WE^COWDiSlZEi average h maximum \ 

40g6 32600 )] 
[REPLICATE I NOREPLICATE ] 
[REUSE I NOREUSE ] 
[SHAREOPTIONSC crossregion 

[b crosssystem ] 1 1. 3)] 
[SPEED I RECOVERY ] 
[STAGE I BIND 1 CYLINDERFAULT] 
[TOidate)\¥ORidays)] 
[UNIQUE I SUBALLOCATION ] 
[UNIQUEKEY | NONUNIQUEKEY ] 
[VVDATEPWipassword )] 
[ UPGRADE 1 NOUPGRADE] 
[WRTTECHECK | NOWRTTECHECK] ) 



(Continued on next page.) 
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[DATA 

([ATTEMPTSinumber)] 
[AUTHORIZATION( entrypoint { fe string ])] 
[BUFFERSPACE(5ire)] 
[COOEicode)] 

[CONTROLINTERVALSIZE( Jize )] 
[COKmOluVyVipassword )] 
[CYLINDERS(/7nmarv [ b secondary ]) | 

VtECOKDSiprimary [ b secondary ]) | 

TRACKS(/7n>nflrv [ b secondary ])] 
[DESTAGEWATT ! NODESTAGEWAIT] 
[ERASE I NOERASE] 
[EXCEPTIONEXIT( entrypoint )] 
[¥llM{dname)] 

[FREESPACE(C/-perce«f [b CA-percent ])] 
[KEYRANGES((/oH'^ev b highkey) 

[( /owArey b highkey )...])] 
[KEYS(/e«^r/i b o//5eO] 
[MASTERPW(/?as5ivor^ )] 
[MODEL( entryname [/password ] 

[hcatnameU password]])] 
[NAME( entryname )] 
[ORDERED I UNORDERED] 
[OWNERi owner id)] 
[READPWipassword )] 
[RECORDSIZE(awra^e b maximum )] 
[REUSE I NOREUSE] 

[SHAREOPTIONS( crossregion [ b crosssystem ])] 
[SPEED I RECOVERY] 
[STAGE I BIND | CYLINDERFAULT] 
[UNIQUE I SUBALLOCATION] 
[UNIQUEKEY | NONUNIQUEKEY] 
[UPDATEPW(/;as5worJ )] 
[VOLUMES( voter [b volser...])] 
[WRTTECHECK | NOWRTTECHECK] )] 



(Continued on next page.) 
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[INDEX 

([ATTEMPTSC number )] 

[AUTHORIZATIONC enrrv/^omr [b string ])] 

[CODEicode)] 

[CONTROLINTERVALSIZE(size )] 

[CONTROLPV/ipassword )] 

[CYLINDERS(pnmar)' [ fe secondary ]) | 
HECORDSiprimary [ b secondary ]) | 
TRACKSiprimary [ b secondary ])] 

[DESTAGEWATT | NODESTAGEWATT] 

[EXCEPTIONEXITC entrypoint )] 

{YlLEidname)] 

[IMBED I NOIMBED] 

[MASTERPW(/7as5wor J )] 

\^ODEL{entryname {/password^ 
[b catname [/ password^y\ 

[N AME( entryname )] 

[ORDERED I UNORDERED] 

[OWNER(ownerwf)] 

[VCE.hD¥^ {password )] 

[REPLICATE I NOREPLICATE] 

[REUSE I NOREUSE] 

[SHAREOPnONS( cro55regio« [b crosssystem ])] 

[STAGE I BIND | CYLINDERFAULT] 

[UNIQUE I SUBALLOCATION] 

[UPDATEPW(i?as5worJ )] 

[VOLUMES( voter [b volser ...])] 

[WRTTECHECK | NOWRTTECHECK] )] 

[CATALOG! catname [/password ])] 



DEFINE ALTERNATEINDEX Parameters: Summary 



The parameters of the DEFINE ALTERNATEINDEX command can be 
grouped as required and optional parameters. 

The required parameters are: 

• Entry type, which specifies that an alternate index and its catalog entry are 
to be created (ALTERNATEINDEX). 

• Name, which names the alternate index (NAME). 

• Base cluster, which identifies the base cluster related to the alternate index 
(RELATE). 

• Allocation, which specifies the amount of space to be allocated to the 
alternate index and identifies the volume(s) that is to contain the alternate 
index (VOLUMES and one of CYLINDERS, RECORDS, or TRACKS). 
You need not explicitly specify the allocation parameters if you use the 
MODEL parameter. 
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The optional parameters are: 

• Model, which identifies an existing alternate index entry that is to be used 
as a model for the alternate index being defined (MODEL). 

• Allocation, which specifies 

- the name of the DD statement that describes the alternate-index's 
volume(s) (FILE). 

- the length and offset of the alternate-key field in the base cluster 
(KEYS). 

- whether the alternate-index records are to be divided by alternate-key 
value among volumes (KEYRANGES). 

- whether the alternate-key value can identify more than one data record 
in the base cluster (UNIQUEKEY or NONUNIQUEKEY). 

- the size of control intervals, records, and the user program's buffer area 
(CONTROLINTERVALSIZE, RECORDSIZE, and BUFFERSPACE). 

- how an alternate index or component that is stored on a mass storage 
device is to be staged (STAGE, BIND, or CYLINDERFAULT). 

- the amount of free space to be left in control intervals and control areas 
when the alternate-index records are loaded (FREESPACE). 

- whether the alternate index is to share its data space with other VSAM 
objects (SUBALLOCATION or UNIQUE). 

~ whether the volumes are to be allocated in the order given with the 
VOLUMES parameter (ORDERED or UNORDERED). 

- whether the alternate index is to be temporary and reusable (REUSE or 
NOREUSE). 

• Data integrity, which specifies 

- the name of a user- written I/O error routine (EXCEPTIONEXIT). 

- whether alternate-index records are to be overwritten with zeros when 
the alternate index is deleted (ERASE or NOERASE). 

- whether the alternate index can be shared among subtasks, jobs, and 

systems (SKAREOFTiONS). 

- whether the alternate-index records are to be checked when the direct 
access device writes them into secondary storage (WRITECHECK or 
NOWRITECHECK). 

- whether an alternate index or component, stored on a mass storage 
volume, is to be destaged synchronously or asynchronously with respect 
to the user's program that closes it (DESTAGEWAIT or 
NODESTAGEWATT). 

- whether space is to be preformatted when the alternate index is initially 
loaded (RECOVERY or SPEED). 

- whether VSAM is to upgrade the alternate index each time its base 
cluster is modified (UPGRADE or NOUPGRADE). 

• Protection, which 

- specifies passwords for the alternate index (MASTERPW, 
CONTROLPW, UPDATEPW, and READPW). 
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- identifies the alternate index to a console operator without revealing its 
entry name (ATTEMPTS and CODE). 

- identifies a user-written-security-verification routine for additional 
authorization verification (AUTHORIZATION). 

- identifies the alternate index's owner (OWNER). 

- specifies a retention period for the alternate index (FOR or TO). 

• Parameters that apply to the index of an alternate index, which specify 

- whether index records are to be repeated around the track of the index's 
direct access device (REPLICATE or NOREPLICATE). 

- whether the index's sequence-set records are to be written adjacent to 
their data control areas (IMBED or NOIMBED). 

• Components, which specifies attributes for the alternate-index's data and 
index components that might differ from the attributes specified for the 
alternate index as a whole or the attributes established for the alternate 
index being used as a model (DATA and INDEX). 

• Catalog, which identifies the catalog in which the alternate index is to be 
defined (CATALOG). 

DEFINE can be abbreviated DEF. 



DEHNE ALTERNATEINDEX Parameters 



Required Parameters 



ALTERNATEINDEX 

specifies that an alternate index is to be defined and have space allocated. 

The ALTERNATEINDEX keyword is followed by the parameters 
specified for the alternate index as a whole. These parameters are enclosed 
in parentheses and, optionally, are followed by the DATA and INDEX 
parameters and their subparameters. 

Abbreviation: ADC 

NAME( entryname ) 

specifies the alternate-index's entryname or the name of each of its 
components. The entryname specified for the alternate index as a whole is 
not propagated to the alternate-index's components. You can define a 
separate entryname for the alternate index, its data component, and its 
index component. If no name is specified for the data and index 
component, a name is generated. Because the alternate index, data 
component, and index component are individually named, each can be 
addressed. 

NAME is a required parameter of ALTERNATEINDEX. When NAME is 
not specified as a parameter of DATA or INDEX, VSAM generates an 
entryname for the alternate-index's components. 

entryname 

can contain 1 to 44 alphameric characters (A through Z, and through 
9), national characters (@, #, and $), and special characters (the 
hyphen (-), and the 12-0 overpunch (X'CO')). 

When the name contains more than eight characters, you divide the 
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name into segments of 1 to 8 characters each and separate the segments 
with (.) periods. The name's first character (and each segment's first 
character) is either an alphabetical character or a national character. If 
you specify the name in the format entryname(modifier), only that 
portion of the name preceding the left parenthesis will be used. The 
modifier enclosed in parentheses will be ignored. 

RELATE ( entryname [ / password ] ) 

names the alternate-index's base cluster. The base cluster is an 
entry-sequenced cluster or a key-sequenced cluster that the alternate index 
is to be organized over. 

You can relate an alternate index only to a key-sequenced cluster or to an 
entry-sequenced cluster. You cannot relate an alternate index to a reusable 
cluster or to a relative-record cluster. 

entryname 

names the base cluster. 

password 

specifies the base cluster's master password. 

You must specify the base cluster's master password when the base 
cluster is password protected. If you do not specify the base cluster's 
master password, you can specify the catalog's master password (that is, 
the master password of the catalog that contains the base cluster's 
entry — see the CATALOG parameter). If no password is specified with 
either the RELATE or the CATALOG parameter, VSAM asks the 
operator for the base cluster's master password. 

Abbreviation: REL 

CYLINDERS( primary [b secondary]) | 

RECORDS( primary [b secondary ) | 

TRACHLSi primary [b secondary]) 

specifies the amount of space to be allocated to the alternate index from 
the volume's available space, when UNIQUE is specified, or from the 
available space of one of the volume's VSAM data spaces. If you specify 
RECORDS, the amount of space allocated is the minimum number of 
tracks that are required to contain the specified number of records. 
However, if you specify TRACKS or RECORDS and if the minimum 
number of tracks should exceed a cylinder, space is allocated in terms of 
cylinders. 

When UNIQUE is specified and the data component is to be contained on 
more than one volume, each volume can contain a maximum of 16 extents. 

When the data component is not divided into key ranges and more than 
one volume is specified, the primary amount of space is allocated only on 
the first volume when the component is defined. When the component 
increases in size so as to extend on to additional volumes, the first 
allocation on each overflow volume is the primary amount. 

When KJEYRANGES is specified and the data component is to be 
contained on more than one volume, the primary amount of space is 
immediately allocated on each volume required for the key ranges. If more 
than one key range is allocated on a single volume, the primary amount is 
allocated for each key range. 
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secondary amounts can be allocated on all volumes available to contain 
parts of the alternate index regardless of the key ranges when the alternate 
index is extended. 

The primary and each secondary allocation must be able to be satisfied 
within 5 extents; otherwise, your DEFINE or data set extension will fail. 

If you do not specify the MODEL parameter, you must specify one, and 
only one, of the following parameters: CYLINDERS, RECORDS, or 
TRACKS. You can specify the amount of space as a parameter of 
ALTERNATEINDEX, as a parameter of DATA, or as a parameter of 
both DATA and INDEX. If the space is specified as a parameter of: 

• ALTERNATEINDEX, the amount specified is divided between the 
data and index components. The division algorithm is a function of 
control interval size, record size, device type, and other data set 
attributes. If the division results in an allocation for the data component 
which is not an integral multiple of the required control-area size, the 
data component's allocation is rounded up to the next higher 
control-area multiple. This rounding may result in a larger total 
allocation for your alternate index than that which you specified. 

• DATA, the entire amount specified is allocated to the data component. 
An additional amount of space, depending on control interval size, 
record size, device type, and other data set attributes, is allocated to the 
index component. 

When you specify UNIQUE, and the amount of space you specify for the 
data component of the alternate index is not an even multiple of cylinder 
size, VSAM rounds the allocation upward to a multiple of a cylinder. 

To determine the exact amount of space allocated to each component, list 
the alternate-index's catalog entry, using the LISTCAT command. 

When you specify UNIQUE and the alternate-index's data space is the first 
data space on a volume that belongs to a recoverable catalog, one 
additional cylinder is allocated for the catalog recovery area. 

primary 

specifies the initial amount of space that is to be allocated to the 
alternate index. 

secondary 

specifies the amount of space that is to be allocated each time the 
alternate index extends, as a secondary extent. When secondary is 
specified, space for the alternate-index's data and index components can 
be expanded to include a maximum of 123 extents. 

If the data space that contains (all or part of) the cluster cannot be 
extended because the cluster's secondary allocation amount is greater 
than the data space's secondary allocation amount, VSAM builds a new 
data space. The new data space's primary and secondary allocation 
amounts are equal to the cluster's secondary allocation amount. 

primary and secondary can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B*n') form. 

Abbreviations: CYL, REC, and TRK 
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VOLUMES( voiser [b volser ... ]) 

specifies the volume(s) on which an alternate-index's components are to 
have space. 

If you do not specify the MODEL parameter, VOLUMES must be 
specified either as a parameter of ALTERNATEINDEX, or as a 
subparameter of both DATA and INDEX. If the data and index 
components are to reside on different device types, you must specify 
VOLUMES as a parameter of both DATA and INDEX. 

If more than one volume is listed with a single VOLUMES parameter, the 
volumes must be of the same device type. The volume serial number may 
be repeated in the list only if the KEYRANGE parameter is specified. You 
may wish to do this in order to have more than one keyrange on the same 
volume. Even in this case, repetition is only valid if all duplicate 
occurrences are used for the primary allocation of some keyrange. 

In a system with the Mass Storage System, an alternate index or 
component can be defined on a mass storage volume. 

volser 

is a 1- to 6-alphameric or national character volume serial number. 

When the volser contains a special character (that is, a comma [,], 
semicolon [;], blank [h], period [.], single Yjuote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the volser in single-quotation marks (for 
example, VOLUMESC*DORIS')). 

When the volser contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, VOLUMES('*CA"ROL')). 

You can code volser in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
VOLUMES(X'E2E4C5') is the same as VOLUMES(SUE). 

The VOLUMES parameter interacts with other DEFINE 
ALTERNATEINDEX parameters. You should take care to ensure that the 
volume(s) you specify for the alternate index can satisfy the alternate 
index's other attributes: 

• SUBALLOCATION: If UNIQUE is not specified, the volume must 
already contain VSAM data space. 

• KEYRANGES: If KEYRANGES and UNIQUE are specified, a VSAM 
data space is built and allocated on a separate volume for each key 
range. 

• ORDERED: If ORDERED is specified, the volumes are used in the 
order listed. If ORDERED and KEYRANGES are specified, there is a 
one-for-one correspondence between the key ranges in the key range 
list and the volumes in the volser list. 

• CYLINDERS, RECORDS, TRACKS: The volume(s) contains enough 
available space to satisfy the component's primary space requirement. 

• FILE: When UNIQUE is specified for the alternate index, the volume 
information supplied with the DD statement pointed to by FILE is 
consistent with the information specified for the alternate index and its 
components. 
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CATALOG: If the volume already has a data space on it, subsequent 
data spaces can be defined for the alternate index and must be cataloged 
in the catalog that owns the volume. 

Abbreviation: VOL 



ATTEMPTSC «Mm6er |2) 

specifies the maximum number of times the operator can try to enter a 
correct password in response to a prompting message. 

This parameter can be coded, but only has effect when the 
alternate-index's master password is not null. A prompting message is 
issued only when the user has not already supplied the appropriate 
password. 

number 

is an integer from to 7 and can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n') form. 

When ATTEMPTS(O) is coded, the operator is not prompted and is not 
allowed to enter a password from the console. 

Note to TSO users: At a TSO terminal, the logon password is checked first 
before the user is prompted to supply a password for the alternate index. 
Checking the logon password counts as one attempt to obtain a password. 
If ATTEMPTS is not specified, the user has one attempt to supply the 
alternate-index's password because the default is 2. 

Abbreviation: ATT 

AUTHORIZATION( entrypoint [fe string ] ) 

specifies that a user-security-verification routine (USVR) is available for 
additional security verification. When a protected alternate index is opened 
and the user supplies a correct password other than the alternate-index's 
master password, the USVR receives control. For details on coding a 
USVR, see the OS/VS Virtual Storage Access Method (VSAM) 
Programmer's Guide. 

If a USVR is loaded from an unauthorized library during Access Method 
Services processing, an abnormal termination will occur. See the section 
"Authorized Program Facility" in the chapter "Introduction." 

This parameter can always be coded, but only has effect when the master 
password is not null. 

entrypoint 

specifies the name of the USVR. entrypoint can contain 1 to 8 
alphameric characters (A through Z and through 9) or national 
characters (@, #, $), and special characters (the hyphen (-) and the 
12-0 overpunch (X*CO')). The name's first character is either an 
alphabetic character or a national character. 

string 

specifies information to be passed to the USVR when it receives control 
to verify authorization, string can contain 1 to 255 EBCDIC characters. 

When the string contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
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plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the string in single-quotation marks (for 
example, AUTHORIZATION ( entrypoint, '*DORIS*')). 

When the string contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, AUTHORIZATION( entrypoint, 
♦*CA"ROL*')). 

You can code string in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
AUTHORIZATION( entrypoint, X'E2E4C5') is the same as 
AUTHORIZATION ( entrypoint, SUE). The string can contain up to 
255 hexadecimal characters when expressed in this form, resulting in up 
to 128 bytes of information. 

Abbreviation: AUTH 

BUFFERSPACE( size ) 

specifies the minimum space that your program's address space is to 
provide for buffers. The buffer space size you specify helps VSAM 

determine the data component's and index component's control interval 
size. 

If the specified size is less than VSAM requires for the buffers needed to 
run your job, VSAM terminates your job and provides an appropriate error 
message. 

When you do not specify BUFFERSPACE, VSAM determines the buffer 
space size. VSAM determines the control interval size first, then sets the 
buffer space amount equal to two data control intervals and one index 
control interval. 

When you specify BUFFERSPACE, you must specify at least enough 
space to contain two data control intervals and one index control interval. 

size 

is the amount of space to be provided for buffers. The value can be 
expressed in decimal (n), hexadecimal (X'n'), or binary (B'n') form. 

Abbreviations: BUFSPC or BUFSP 

CODE'^ cods ) 

specifies a code name for the alternate index. If an attempt is made to 
access a password-protected alternate index withopt first siipplying an 
appropriate password, a prompting message might be issued to the 
operator's console (see ATTEMPTS above). The prompting message 
includes the code name, which identifies the alternate index without 
revealing its entryname. 

This parameter can be coded, but only has effect when the 
alternate-index's master password is not null. A prompting message is 
issued only when the user hasn't already supplied the appropriate 
password. 

When you don't specify a code name for the alternate index, the prompting 
message identifies the alternate index with its entryname. 
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# can contain 1 to 8 EBCDIC characters. When the code contains a 

special character (that is, a comma [,], semicolon [;], blank [b], period 
[.], single quote ['], ampersand [ & ], plus sign [+], equal sign [=], 
hyphen [-], parenthesis [( or )], slash [/], or asterisk [*]), enclose the 
code in single-quotation marks (for example, CODEC*DORIS*')). 

When the code contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, CODE('*CA"ROL*'))- 

You can code code in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
CODE(X'E2E4C5') is the same as CODE(SUE). 

CONTROLINTERVALSIZEC ste ) 

specifies the size of the alternate-index's control intervals. The size of the 
control interval depends on the maximum size of data records, and on the 
amount of buffer space specified. 

When you do not specify the control interval size, VSAM determines the 
control interval size. If you have not specified BUFFERS? ACE and the 
size of your records permits, VSAM selects the optimum size for the data 
control interval size and 512 bjrtes for the index control interval size. 

size 

for the alternate-index's data component. 

Since an alternate index always has the spanned attribute, the control 
interval size can be less than the maximum record length. The sizes you 
J can specify — between 512 and 32,768 b3rtes — are a multiple of 512 or 

2048: 

CISZ = (n X 512) or (n x 2048) 

where n is a positive integer from 1 to 16 

size 

for the alternate-index's index component. 

You can specify the following values for the index component's control 
interveil size: 

CISZ = [512 I 1024 I 2048 I 4096] 

When you specify a size that is not a multiple of 512 or 2048, VSAM 
chooses the next higher multiple. 

Refer to the chapter "Optimizing VSAM's Performance" in OS/VS 
Virtual Storage Access Method (VSAM) Programmer's Guide for a 
discussion of the relationship between control mterval size and physical 
block size. The discussion also includes restrictions that apply to control 
interval size and physical block size. 

Abbreviations: CISZ or CNVSZ 

CONTROLPW( password ) 

specifies a control password for the alternate index and its data and index 
components The control password allows read and write operations 
against the object's control intervals. 

/ When specified as a parameter of DATA or INDEX, the control password 
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allows the user's program to open the data component or index component 
for read and write processing of the component's control intervals (that is, 
the entire control interval, including the data portion of stored records and 
the control fields VSAM inserts into stored records and control intervals). 

If a read or update password is the only password specified for the object, 
it (the highest-level password) propagates upward and becomes the 
password for all higher unspecified levels, 

password 

is a 1- to 8-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, CONTROLPW('*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, CONTROLPW('*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
CONTROLPW(X'E2E4C5') is the same as CONTROLPW(SUE). 

Abbreviation: CTLPW 

DESTAGEWAIT ! NODESTAGEWAIT 

specifies whether an alternate index or its component that is stored on a 
mass storage volume is to be destaged synchronously or asynchronously 
with respect to the program that closes it. 

DESTAGEWAIT indicates that destaging is to be completed before 
VSAM returns control to the program that issued the CLOSE macro. 
VSAM can thus notify the program whether destaging was successful, 

NODESTAGEWAIT indicates that notification of unsuccessful destaging 
is to be made only by a message to the operator. 

When the alternate index or component isn't stored on a mass storage 
volume, the attribute is ineffective until the direct access storage volume 

the alternate index -or ccmponsnt is stored on is converted to a mass 
storage volume (by way of the CONVERTV command, which is described 
in OS/VS Mass Storage Sj'stem (MSS) Services for Reference 
Information). 

When one of these parameters is specified for the data component and the 
other parameter is specified for the index component, the components are 
destaged separately as specified, except when the sequence set of the index 
component is imbedded in the data. In that case, the parameter specified 
for the index component appUes to both components. 

Abbreviations: DSTGW and NDSTGW 

ERASE I NOERASE 

specifies whether the alternate index data component's records are to be 
erased when the alternate index is deleted. If ERASE is specified, the 
alternate index data component's records are overwritten with binary zeros 
when the alternate index is deleted. This attribute applies only to the 
alternate-index's data component. 
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Abbreviations: ERAS aod NERAS 

EXCEPnONEXrrC entrypomt ) 

specifies the name of the user- written routine, called the exception exit 
routine, that receives control when an exceptional I/O error condition 
occurs during the transfer of data between your program's address space 
and the alternate-index's direct access storage space. (An exception is any 
condition that causes a SYNAD exit to be taken.) The component's 
exception-exit routine is processed first, then the user's SYNAD exit 
routine receives control. 

If an exception exit routine is loaded from an unauthorized library during 
Access Method Services processing, an abnormal termination will occur. 
See the section "Authorized Program Facility" in the chapter 
"Introduction." 

Abbreviation: EEXT 

FILE( dname ) 

names the DD statement that identifies the dkect access device(s) and 
volume(s) on which space is to be allocated to the alternate index. When 
you specify UNIQUE, FILE can identify the DD statement which 
identifies and allocates the volumes of the alternate index. If more than one 
volume is specified in a volume list, all volumes must be the same device 
tjrpe. When the data component and index component are to reside on 
separate devices, you can specify a separate FILE parameter as a 
subparameter of DATA and INDEX to point to different DD statements. 

When the alternate index is defined in a recoverable catalog, and FILE is 
specified as a parameter of ALTERNATEINDEX, the FILE parameter 
can identify the DD statement for all volumes on which space is to be 
allocated. You also use FILE to identify the volume containing the base 
cluster's index component (when the base cluster is key-sequenced) or data 
component (when the base cluster is entry-sequenced) when defining into 
a recoverable catalog. When FILE refers to more than one volume of the 
same device type, the DD statement that describes the volumes cannot be a 
concatenated DD statement. When the alternate index is cataloged in a 
recoverable catalog, the DD statement can be concatenated if the volumes 
are a different device type: part of the concatenated DD statement 
describes the alternate index's or component's volumes (of one device 
type); the other part of the DD statement describes the volume that 
contains the catalog recovery area (of another device type). 

If the FILE parameter is not specified, the required volumes are 
dynamically allocated. If the alternate index or one of its components is 
unique, and if the FILE parameter is not specified and the volume(s) is 
physically mounted, the volume (s) identified with the VOLUMES 
parameter is dynamically allocated. The volume(s) must be mounted as 
permanently resident or reserved. 

The DD statement you specify must be in the form: 

//ddname DD UNIT=( devtype [ , unitcount ] ), 
// VOL=SER=( \okerl, volser2, wiser, ...), ... 
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FREESPACE( CI -percent [b CA-percent]\ 0) 

specifies the amount of space that is to be left empty after any allocation 
(that is, the initial, or primary, allocation and each extension, or secondary 
allocation) and any split of control intervals (Cl-percent) and control areas 
(CA-percent) when the alternate index is built (see the BLDINDEX 
command). The amount of empty space in the control interval and control 
area is available for data records that are updated and inserted after the 
alternate index is initially built. 

The amounts are specified as percentages. Cl-percent translates into a 
number of bytes that is equal to, or sUghtly less than, the percentage value 
of Cl-percent. CA-percent translates into a number of control intervals 
that is equal to, or less than, the percentage value of CA-percent. The 
percentages, which must be equal to or less than 100, can be expressed in 
decimal (n), hexadecimal (X'n'), or binary (B'n') form. 

When you specify 100 percent of free space, one data record is placed in 
the first control interval of each control area when the alternate index is 
built. 

Abbreviation: FSPC 

IMBED ! NOIMBED 

specifies whether the sequence set (that is, the lowest level of the index of 
the alternate index—the level that points to alternate-index records) is to 
be put adjacent to the alternate-index's data component, » 

When you specify IMBED, the sequence-set record for each control area is 
written as many times as it will fit on the first track adjacent to the control 
area. 



The IMBED | NOIMBED parameter interacts with the ^ 

REPLICATE I NOREPLICATE parameter in determining the physical 
attributes of the index of the alternate index. These index attributes can be 
used in the following combinations: 

• The sequence-set records are adjacent to the data control areas, and 
only the sequence-set records are repUcated (IMBED and 
NOREPLICATE). 

• The sequence-set records are adjacent to the data control intervals, and 
all levels of index records are replicated (IMBED and REPLICATE). 

• All index records are together, and aM index records are replicated 
(REPLICATE and NOIMBED). 

• All index records are together, and no index records are replicated 
(NOREPLICATE and NOIMBED). 

For some applications, specifying index options can improve the 
application's performance. See OS/VS Virtual Storage Access Method 
(VSAM) Programmer's Guide for information on how the index's optional 
attributes affect performance. 

Abbreviations: IMBD and NIMBD 

KEYRANGES(( lowkey h highkey ) 

[ ( lowkey b highkey )...]) 

specifies that portions of the alternate-index's data component are to be 
put on different volumes. Each portion of the alternate index is called a 
key range. 
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The maximum number of alternate-key ranges is 123. Key ranges must be 
in ascending order, and aren't allowed to overlap. However, a gap can exist 
between two key ranges — you are not allowed to insert records within the 
gap. 

Keys can contain 1 to 64 characters; 1 to 128 hexadecimal characters if 
coded as X' lowkey ' b X' highkey '. All EBCDIC characters are allowed. 
Keys consisting of characters must be enclosed in single quotation marks if 
they contain commas, semicolons, blanks, parentheses, or slashes. A single 
quotation mark within a key must be coded as two single quotation marks 
if the key is enclosed in single quotation marks, 

lowkey 

specifies the low key of the key range. If lowkey is shorter than the 
actual keys, it will be padded on the right with binary zeros. 

highkey 

specifies the high key of the key range. If highkey is shorter than the 
actual keys, it will be padded on the right with binary ones. 

The KEYRANGES parameter interacts with other DEFINE 
ALTERNATEINDEX parameters. You should take care to ensure that, 
when you specify KEYRANGES, the alternate-index's other attributes can 
be satisfied. 

• VOLUMES: There should be as many volume-serial-numbers in the 
volser list as there are key ranges. When a volume serial number is 
duplicated in the vober list, more than one key range is allocated space 
on the volume. When more than one key range is contained on a 
volume, UNIQUE cannot be coded for the alternate-index's data 
component. 

When there are more volumes in the volser list than there are key 
ranges, the excess volumes are used for overflow records from any key 
range without consideration for key range boundaries. 

When there are fewer volumes in the volser list than there are key 
ranges, the excess key ranges are allocated on the last volume 
specified — ^UNIQUE cannot also be specified. 

• UNIQUE: When UNIQUE is specified, each key range resides in its 
own VSAM data space on a separate volume. Other key ranges for the 
alternate index cannot also reside on the volume. 

• ORDERED: There is a one-for-one correspondence between the 
volumes in the volser list and the key ranges: the first volume on the 
volume list contains the first key range, the second volume contains the 
second key range, and so on. If a volume can't be allocated in the order 
specified by the volser Ust, your alternate index definition job terminates 
with an error message. 

• KEYS: the length of the key values must not exceed the key length 
specified in the KEYS parameter. 

Abbreviation: KRNG 
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KEYS( length fe offset | 64 ) 

describes the alternate-key field in the base cluster's data record. The key 
field of a key-sequenced cluster is called the prime key, to distinquish it 
from other key fields, called alternate keys. The data record's alternate key 
can overlap or be contained entirely within another (alternate or prime) 
key field. 

The sum of length plus offset cannot be greater than the length of the 
base cluster's data record. 

When the base cluster's data record is allowed to span control intervals, the 
record's alternate-key field is within the record's first segment (that is, in 
the first control interval.) 

length b offset 

specifies the length of the alternate key (between 1 and 255), in bytes, 
and its displacement from the beginning of the base cluster's data 
record, in bytes. You can express length and offset in decimal (n), 
hexadecimal (X'n'), or binary (B'n') form. 

MASTERPW( password ) 

specifies a master password for the alternate index. The master password 
allows all Access Method Services operations against the alternate index 
entry and its data and index entries. The master password allows the user's 
program to access the alternate-index's contents without restriction. For 
more details on how passwords can be used, see "Data Security and 
Protection." 

If all passwords are null, ATTEMPTS, AUTHORIZATION, and CODE 
can be specified but have no effect until the master password is specified. 

When specified as a parameter of DATA or INDEX, the master password 
allows the user's program to open the data component or index component 
and process it without restriction. 

When you don't specify MASTERPW, but do specify another password, 
the object's highest-level password propagates upward and becomes the 
password for all higher levels, including the master password. 

password 

is a 1- to 8-EBCDIC-character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [h], period 1.1, single quote 1']. ampersand F & 1, 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, MASTERPW('*DORIS*').) 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, MASTERPWC*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
MASTERPW(X'E2E4C5') is the same as MASTERPW(SUE). 

Abbreviation: MRPW 

MODEL ( entryname [ / password ] 
[ b catname [ / password ]] ) 

identifies an existing alternate index entry that is to be used as a model for 

the alternate index being defined. 



202 OS/VS2 Access Method Services 



DEFINE ALTERNATEINDEX 

\ When you use an alternate index entry as a model for the alternate index, 

^ the model alternate-index's data and index entries are used as models for 

the to-be-defined alternate-index's data and index components, unless 
another entry is specified with the MODEL parameter as a subparameter 
of DATA or INDEX. 

You can use an existing data entry as a model for the alternate-index's data 
component, and/or an existing index entry as a model for the 
alternate-index's index component, without specifying a model for the 
alternate index itself. 

You can use some attributes of the model entry and override other 
attributes by explicitly specifying them in the alternate-index's definition. 
For details about how a model is used, see "How to Use One Object as a 
Model for Another Object." When you do not want to add or change any 
attributes, you specify only the entry type (ALTERNATEINDEX), the 
alternate-index's name (NAME), its base cluster's name (RELATE) and 
the model-entry's name (MODEL). 

entryname 

names the entry to be used as a model, entryname names an alternate 
index entry when MODEL is a parameter of ALTERNATEINDEX. 

entryname names an alternate-index's data entry when MODEL is a 
parameter of DATA, and it names an alternate-index's index entry 
when MODEL is a parameter of INDEX. 

password 

specifies a password. If the model entry is password protected and it is 
) cataloged in a password-protected catalog, you supply the read- (or 

higher-level) password of either the model entry or its catalog. If you 
supply both passwords, the catalog's password is used. 

If you are not specifying new protection attributes for the alternate 
index and you wish to copy the model's passwords and protection 
attributes, you must supply the master password of either the model 
entry or its catalog. 

catname 

names the model-entry's catalog. You must identify the catalog that 
contains the model entry when: 

• You want to specify the catalog's password instead of the 
model-entry's password. 

• The model-entry's catalog is not identified with a JOBCAT or 
STEPCAT DD statement, and is not the master catalog. 

If the catalog's volume is physically mounted, it is dynamically allocated. 
The volume must be mounted as permanently resident or reserved. See 
"Order of Catalog Use: DEFINE" for information about the order in 
which a catalog is selected when the catalog's name is not specified. 

ORDERED I UNORDERED 

specifies whether volumes are to be used in the order in which they are 
listed in the VOLUMES parameter. 

When you want each key range to reside on a separate volume, you can use 
n ORDERED so that the first key range goes on the first volume, the second 

'^ key range goes on the second volume, and so on. 
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If ORDERED is specified and tlie volumes cannot be allocated in the order 
specified, the command is terminated. 

Abbrefiatioiis: ORD and UNORD 

OWNER( ownerid ) 

specifies the identification of the alternate-index's owner. 

ownerid 

can contain 1 to 8 EBCDIC characters. When the ownerid contains a 
special character (that is, a comma [,], semicolon [;], blank [b], period 
[.], single quote ['], ampersand [ & ], plus sign [+], equal sign [=], 
hyphen [-], parenthesis [( or )], slash [/], or asterisk [*]), enclose the 
ownerid in single-quotation marks (for example, 
OWNERC*DORIS*')). 

When the ownerid contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, OWNERC*CA"ROL*')). 

You can code ownerid in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
OWNER(X*E2E4C5') is the same as OWNER(SUE). 

Note to TSO usens: If the owner is not identified with the OWNER 
parameter, the TSO user's userid becomes the ownerid. 

READPW( password ) 

specifies a read password for the alternate index or its data or index 
component. The read password permits read operations against the 
alternate-index's data records. 

When specified as a parameter of DATA or INDEX, the read password 
allows the user's program to open the data component or the index 
component for read-only .processing of the component's data records (that 
is, the data portion of the sorted record, not the control fields VSAM 
inserts into stored records). For more details on how passwords can be 
used, see "Data Security and Protection." 

password 

is a 1- to 8-EBCDIC-chafacter password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, READPWC*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, READPW('*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
READPW(X'E2E4C5') is the same as READPW(SUE). 

Abbreviation: RDPW 
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RECORDSIZEC average h maximum \ 4086 32600 ) 

specifies the average and maximum length, in bytes, of an alternate-index 
record. 

An alternate-index record can span control intervals, so RECORDSIZE 
can be larger- than CONTROLINTERVALSIZE. average and maximum is 
any integer value that does not exceed the capacity of a control area, and 
can be expressed in decimal (n), hexadecimal (X'n'), or binary (B'n') form. 
You can identify the records as fixed length by specifying the same value 
for average and maximum. 

You can use the following formulas to determine the size of the 
alternate-index record when the alternate index supports: 

• a key-sequenced base cluster 

RECSZ = 5 + AIXKL + (n x BCKL) 

• an entry-sequenced base cluster 

RECSZ = 5 + AIXKL H- (n x 4) 
where: 

- RECSZ is the average record size. 

- AIXKL is the alternate-key length (see the KEYS parameter). 

- BCKX is the base cluster's prime-key length (you can issue the 
Access Method Services LISTCAT command to determine the base 
cluster's prime-key length). 

- n = 1 when UNIQUEKEY is specified (RECSZ is also the maximum 
record size). 

- n = the number of data records in the base cluster that contain the 
same alternate-key value, when NONUNIQUEKEY is specified. 

When you also specify NONUNIQUEKEY, the record size you specify 
should be large enough to allow for as many key pointers or RBA pointers 
as you anticipate. The record-length values apply only to the 
alternate-index's data component. 

If you plan to copy your alternate index using either the EXPORT or 
EXPORTRA command, you should be aware of the restriction in 
maximum record length imposed- by these commands. Refer to the sections 
"Moving Entries" and "Copying a Catalog Entry From the Catalog 
Recovery Area" for details of this restriction. 

Abbreviation: RECSZ 

REPLICATE I NOREPLICATE 

specifies whether each index record (that is, each record in the 
alternate-index's index component) is to be written on a direct-access 
device track as many times as it will fit. 

When you specify REPLICATE, rotational delay is reduced and 
performance is improved. However, the alternate-index's index usually 
takes more direct-access device space. 

Refer to the description of the IMBED | NOIMBED parameter for a 
discussion of the relationship between IMBED | NOIMBED and 
REPLICATE I NOREPLICATE. 
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Abbreviations: REPL and NREPL 

REUSE I NOREUSE 

specifies whether the alternate index can be used over and over again as a 
(temporary) new alternate index. When a reusable alternate index is 
opened, its high-used RBA can be set to zero if you open it with an ACB 
which specifies the RESET attribute. When you use Access Method 
Services command, BLDINDEX, to build a reusable alternate index, the 
high-used RBA is always reset to zero when the alternate index is opened 
for BLDINDEX processing. 

You cannot specify REUSE when you also specify KEYRANGES or 
UNIQUE for the alternate index or its components. Reusable alternate 
indexes may be multivolumed and are restricted to sixteen physical, extents 
per volume. 

Abbreviations: RUS and NRUS 

SHAREOPnONS( crossregion [ h crosssystem ] | j[ 3 ) 

specifies how an alternate-index's data or index component can be shared 
among users. See OS/VS Virtual Storage Access Method (VSAM) 
Programmer's Guide for a full description of data-set sharing. 

Unless you specify sharing options, the alternate index cannot be shared. 

crossregion 

specifies the amount of sharing allowed among regions (within the same 
system). Independent job steps in an operating system can access a 
VSAM data set concurrently. To share a data set, each user must specify 
DISP=SHR in the data-set's DD statement. The values that can be 
specified are: 

1 

specifies that the data set can be shared by any number of users for 
read processing, or the data set can be accessed by only one user for 
read and write processing. With this option, VSAM ensures complete 
data integrity for the data set. 

2 

specifies that the data set can be accessed by any number of users for 
read processing and it can also be accessed by one user for write 
processing. With this option, VSAM ensures write integrity by 
obtaining exclusive control for a control interval when it is to be 
updated. If a user desires read integrity, it is his responsibility to use 
the ENQ and DEQ macros appropriately to provide read integrity for 
the data his program obtains. 

3 

specifies that the data set can be fully shared by any number of users. 
With this option, each user is responsible for maintaining both read 
and write integrity for the data his program accesses. User programs 
that ignore the write-integrity guideUnes can cause VSAM program 
checks, lost or inaccessible records, uncorrectable data-set failures, 
and other unpredictable results. This option places heavy 
responsibility on each user sharing the data set. 
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4 

specifies that the data set can be fully shared by any number of users, 
and buffers used for direct processing are refreshed for each request. 
This option requires your program to use the ENQ and DEQ macros 
to maintain data integrity while sharing the data set. Improper use of 
the ENQ macro can cause problems similar to those described under 
SHAREOPTION 3. 

crosssystem 

specifies the amount of sharing allowed among systems. Job steps of 
two or more OS/VS operating systems can gain access to the same 
VSAM data set regardless of the disposition specified in each step's DD 
statement for the data set. To get exclusive control of the data-set's 
volume, a task in one system issues the RESERVE macro. The level of 
cross-system sharing allowed by VSAM applies only in a multiple 
operating system environment. The values that can be specified are: 

1 

Reserved 

2 

Reserved 

3 

specifies that the data set can be fully shared. With this option, each 
user is responsible for maintaining both read and write integrity for 
the data his program accesses. User programs that ignore 
write-integrity guidelines can cause VSAM program checks, 
uncorrectable data set failures, and other unpredictable results. This 
option places heavy responsibility on each user sharing the data set. 

4 

specifies that the data set can be fully shared. Buffers used for direct 
processing are refreshed for each request. This option requires that 
you use the RESERVE and RELEASE macros to maintain data 
integrity while sharing the data set. Writing is limited to PUT-update 
and PUT-insert processing that does not change the high-used RBA 
if your program opens the data set with DISP=SHR. Data set 
integrity caimot be maintained unless all jobs accessing the data set in 
a cross-system environment specify DISP=SHR. Improper use of the 
RESERVE macro can cause problems similar to those described 
under SHAREOPTION 3. 

The assistance VSAM provides each user's program to ensure data 
integrity in a shared environment is: 

• Each PUT request results in the appropriate buffer being written 
immediately into the VSAM object's direct-access device space. VSAM 
writes out the buffer in the user's address space that contains the new or 
updated data record. 

• Each GET request results in all of the user's input buffers being 
refreshed. Each buffer's contents (that is, each data and index buffer 
being used by the user's program) is retrieved from the VSAM object's 
direct-access device. 

For data integrity purposes, you should make sure that share options 
specified for data and index components are the same. Additional 
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infonnation about shared data can be found in OS/VS Virtual Storage 
Access Method (VSAM) Programmer's Guide. 

Abbreviation: SHR 

SPEED I RECOVERY 

specifies whether the data-component's control areas are preformatted 
before alternate-index records are loaded into them. When RECOVERY is 
specified, the data-component's control areas are written with records that 
indicate end-of-file. When an alternate-index record is written into a 
control interval, it is always followed by a record that identifies the 
just-written record as the last record in the alternate index. If the initial 
load fails, you can resume loading alternate-index records after the last 
correctly-written record (because an end-of-fUe indicator identifies it as 
the last record — that is, no more alternate-index records follow). 

When SPEED is specified, the data-component's space is not preformatted. 
Its space might contain data records from a previous use of the space, or it 
might contain binary zeros — its contents are unpredictable. If the initial 
load faOs, you must load the alternate-index records again from the 
beginning (because VSAM is unable to determine where your last 
correctly-written record is — VSAM cannot find a valid end-of-fUe 
indicator when it searches your alternate-index records). 

When you specify RECOVERY, your initial load takes longer because the 
control areas are written initially with end-of-file indicators, and again with 
your alternate-index records. When you specify SPEED, your initial load is 
quicker. 

Abbreviation: RCVY 

STAGE I BIND | CYLINDERFAULT 

specifies how an alternate index or component that is stored on a mass 
storage volume is to be staged. 

STAGE 

indicates that the alternate index or component is to be staged from 
mass storage to a direct-access storage staging drive when the alternate 
index or component is opened. If the alternate index or component 
cannot be staged at open time because of heavy staging activity of other 
objects, data is staged as a processing program needs it. 

BIND 

indicates that the alternate index or component is not only to be staged, 
but also to be bound — that is, retained on the direct-access storage 
staging drive until it is closed. If the alternate index or component 
cannot be staged at open time because of heavy staging activity of other 
objects, data is staged as a processing program needs it. 

CYLINDERFAULT 

indicates that the alternate index or component is not to be staged when 
it is opened, but that data from it is to be staged as a processing program 
needs it. 

Abbreviation: CYLF 

When the alternate index or component not stored on a mass storage 
volume, the attribute is ineffective until the direct-access storage volume 
the alternate index or component is stored on is converted to a mass 
storage volume (by way of the CONVERTV command, which is described 
in OS/VS Mass Storage System (MSS) Services: Reference Information). 
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When one of these parameters is specified for the data component and 
another parameter is specified for the index component, the components 
are staged separately as specified, except when the sequence set of the 
index component is imbedded in the data. In that case, the parameter 
specified for the index component applies to both components. 

TO( date ) | FOR( days ) 

specifies the retention period for the alternate index. The alternate index is 
not automatically deleted when the expiration date is reached. When you 
do not specify a retention period, the alternate index can be deleted at any 
time. 

TO( date ) 

specifies the date, in the form yyddd, where yy is the year and ddd is 
the Julian date (001, for January 1, through 365, for December 31), 
through which the alternate index is to be kept before it is allowed to be 
deleted. 

FOR( days ) 

specifies the number of days for which the alternate index is to be kept 
before it is allowed to be deleted, days can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n') form. The maximum number that 
can be specified for days is 9999. If the number specified is through 
1830, the retention period is the number of days specified. If the 
number specified is between 1831 and 9999, the retention period is 
through the year 1999. 

UNIQUE 1 SUBALLOCATION 

specifies whether the alternate-index's components are allocated an 
amount of space from the volume's available space (UNIQUE) or from a 
VSAM data-space's available space (SUBALLOCATION.) 

When UNIQUE is specified, a VSAM data space is built and is assigned 
exclusively to each component of the alternate index. The data space is 
created when the alternate index is defined. The alternate-index's 
volume(s) must be mounted. VSAM builds a DSCB in the volume's table 
of contents (VTOC) to describe the data space. The name of the data 
space, which is the same as the component's name, is put in the DSCB. A 
subentry is added to the volume entry (in the VSAM catalog) to describe 
the VSAM data space. 

When SUBALLOCATION is specified, space from one of the VSAM data 
spaces on the volume is assigned to the alternate-index's component. 

The space-aUocation attribute interacts with other DEFINE 
ALTERNATEINDEX parameters. You should take care to ensure that the 
attribute you specify for the alternate index is consistent with other 
attributes: 

• REUSE: You cannot specify REUSE when you specify UNIQUE for an 
alternate index or its components. 

• KEYRANGES: When UNIQUE is specified, a data space is built and 
allocated on a separate volume for each key range. 
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• VOLUMES: When UNIQUE is not specified, VSAM data space must 
exist on the volume that is to contain the alternate-index's component. 
When UNIQUE is specified, and more than one volume is specified, 
VSAM most already own all the volumes except the first. If there is no 
VSAM space on a volume, you must execute a DEFINE SPACE 
CANDIDATE before your DEFINE UNIQUE. 

Abbreviations: UNQ and SUBAL 

UNIQUEKEY | NONUNIQUEKEY 

specifies whether more than one data record (in the base cluster) can 
contain the same alternate-key value. 

UNIQUEKEY specifies that each alternate key points to only one data 
record. When the alternate index is built (see the BLDINDEX command) 
and more than one data record contains the same alternate-key value, the 
BLDINDEX processing terminates with an error message. 

NONUNIQUEKEY specifies that an alternate-key value might point to 
more than one data record in the base cluster. The alternate-key record can 
point to a maximum of 32,768 records with nonunique keys. 

When you specify NONUNIQUEKEY, the value you specify as the 
maximum record size should be large enough to allow for alternate-index 
records that point to more than one data record. 

Abbreviations: UNQK and NUNQK 

UPDATEPW( password ) 

specifies the update password for the alternate index or its data or index 
component. The update password permits read and write operations 
against the alternate-index's data records. 

When specified as a parameter of DATA or INDEX, the update password 
allows the user's program to open the data component or index component 
for read and write processing of the component's VSAM records (that is, 
the data portion of the stored record, not the control fields VSAM inserts 
into stored records). 

If a read password is the only password specified for the object (that is, it 
is the highest-level password), it propagates upward and becomes the 
password for all higher levels. If yuu specify a higher-ievei password and 
do not specify an update password, the update or read password is null. 

password 

is a 1- to 8-EBCDIC-character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [fe], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, UPDATEPWC*DORIS*').) 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, UPDATEPWC*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
UPDATEPW(X'E2E4C5') is the same as UPDATEPW(SUE). 

Abbreviation: UPDPW 
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UPGRADE I NOUPGRADE 

specifies whether the alternate-index is to be upgraded (that is, kept up to 
date) when its base cluster is modified. UPGRADE specifies that when the 
base-cluster's records are added to, updated, or erased, the cluster's 
alternate index is upgraded to reflect the changed data. 

When UPGRADE is specified, the alternate index's name is cataloged with 
the names of other alternate indexes for the base cluster. The group of 
alternate-index names identify the upgrade set — all of the base cluster's 
alternate indexes that are opened when the base cluster is opened for write 
operations. 

The UPGRADE attribute is not effective for the alternate index until the 
alternate index is built (see the BLDINDEX command). If the alternate 
index is defined when the base cluster is open, the UPGRADE attribute 
takes effect the next time the base cluster is opened. 

Abbreviations: UPG and NUPG 

WRTTECHECK | NOWRTTECHECK 

specifies whether an alternate-index's data or index component is to be 
checked (by a direct-access device operation called write-check) when a 
record is written to the device. If WRITECHECK is specified, the record is 
written to the device, then read without data transfer to test for the 
data-check condition. 

Abbreviations: WCK and NWCK 



Attributes can be specified separately for the alternate-index's data and index 
components. 

DATA( options ) 

specifies attributes for the alternate-index's data component. Except for 
name, space allocation, and protection attributes, attributes specified as 
parameters of DATA override the same attributes specified as parameters 
of ALTERNATEINDEX. Attributes specified as parameters of DATA can 
also be used to override the same attributes of a data entry that is used as a 
model. 

Parameters that can be specified for the alternate-index's data component 
are: 

• ATTEMPTS, AUTHORIZATION, and CODE: Specifies protection 
attributes for the data component when it is opened as a separate 
VSAM object by the user's program. 

• BUFFERSPACE: Specifies the amount of buffer space that the user's 
program is to provide from its address space when the program opens 
the data component as a separate VSAM object. 

• CONTROLINTERVALSIZE: Specifies the size of the data 
component's control interval The sizes you can specify are: 

CISZ = (n X 5 12) or (n X 2048) 

where n is a positive integer from 1 to 16. 

. CYLINDERS, RECORDS, or TRACKS: Specifies an amount of space 
to be allocated to the data component. When you specify space as a 
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parameter of DATA, you cannot also specify space for the alternate 
index as a whole. (See the description of TRACKS | CYLINDERS | 
RECORDS as parameters of ALTERNATEINDEX.) 

• DESTAGEWAIT or NODESTAGEWAIT: Specifies whether the data 
component, stored on a mass storage volume, is to be destaged 
synchronously or asynchronously with respect to the user's program that 
closes it. 

• ERASE or NOERASE: Specifies whether the data records are to be 
erased when the alternate index is deleted. 

e EXCEPTIONEXIT: Identifies an exception exit routine for the 
alternate index's data component. 

• FILE: Names the DD statement that describes a direct-access device 
and volumes that are to contain the data component. When more than 
one volume is to contain the data component, all volumes must be of the 
same device type. 

• FREESPACE: Specifies the amount of space that is to be left free after 
any allocation and after any split of control intervals and control areas 
when the alternate index is buUt (see the BLDINDEX command). 

• KEYRANGES: Specifies that portions, or key ranges, of the alternate 
index are to be put on different volumes, and specifies the boundaries of 
each key range. 

• KEYS: Describes the alternate-key field of the base cluster's data 
record. 

. MASTERPW, CONTROLPW, UPDATEPW, and READPW: Specifies 
passwords for the data component when it is opened as a separate 
VSAM object by the user's program. 

• MODEL: Identifies a data entry that is to be used as a model for the 
data component only. 

• NAME: Names the data component. If you do not specify a name for 
the data component, VSAM generates one (see "Defining a Cluster" for 
the format of the generated name). 

. ORDERED or UNORDERED: When ORDERED is snerified, the 
volumes Usted with the VOLUMES parameter are allocated in the order 

• OWNER: Identifies the data component's owner, when the owner is 
different from the owner of the alternate index as a whole. 

• RECORDSIZE: Specifies the average and maximum sizes of the 
alternate-index's data records. 

• REUSE or NOREUSE: Specifies whether the alternate index's data 
component is to be reusable. 

• SHAREOPTIONS: Specifies share options for the data component 
when it is opened as a separate VSAM object by the user's program. 

• STAGE, BIND, or CYLINDERFAULT: Specifies whether the data 
component, stored on a mass storage volume, is to be staged. 

. UNIQUE or SUBALLOCATION: Specifies whether the data 
component is to occupy exclusively a VSAM data space or share an 
existing data space with other VSAM objects. 
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. UNIQUEKEY or NONUNIQUEKEY: Specifies whether more than one 
data record (in the base cluster) can contain the same alternate key 
value, 

• VOLUMES: Identifies the volume(s) that is to contain the data 
component, and identifies other volumes that can be used as overflow 
volumes for the data component. 

. WRITECHECK or NOWRTTECHECK: Specifies whether the data 
records are to be checked by the direct-access device when they are 
written into the data component. 

Restrictions are noted with each parameter's description. All of the DATA 
subparameters are described in more detail as parameters of the alternate 
index as a whole. 

INDEX( options ) 

specifies attributes for the index component of an alternate index. 

Except for name, space allocation, and protection attributes, attributes 
specified as parameters of INDEX override the same attributes specified as 
parameters of ALTERNATEINDEX. Attributes specified as parameters of 
INDEX can also be used to override the same attributes of an index entry 
that is used as a model. 

Parameters that can be specified for the alternate-index's index component 
are: 

. ATTEMPTS, AUTHORIZATION, and CODE: Specifies protection- 
attributes for the index when it is opened as a separate VSAM object by 
the user's program. 

• CONTROLINTERVALSIZE: Specifies the index component's control 
interval size. The sizes you can specify are: 512, 1024, 2048, or 4096 
bytes. 

. CYLINDERS, RECORDS, or TRACKS: Specifies an amount of space 
to be allocated to the index component. When you specify one of the 
space-quantity parameters as a parameter of INDEX, you must also 
specify a space-quantity parameter as a parameter of DATA. You 
cannot also specify a quantity of space for the alternate index as a 
whole. 

. DESTAGEWAir or NODESTAGEWAIT: Specifies whether the index 
component, stored on a mass storage volume, is to be destaged 
synchronously or asynchronously with respect to the user's program that 
closes it. 

• EXCEPTIONEXIT: Identifies an exception exit routine for the index 
component. 

• FILE: The DD statement describes a direct-access device that is to 
contain the index component. When more than one volume is to contain 
the index component, aU volumes must be of the same device tjrpe. 

• IMBED or NOIMBED: Specifies whether the sequence set records are 
to be written adjacent to the data. 

. MASTERPW, CONTROLPW, UPDATEPW, and READPW: Specifies 
passwords for the index component when it is opened as a separate 
VSAM object by the user's program. 
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• MODEL: Identifies an index entry that is to be used as a model for the 
index component only. 

• NAME: Names the index component. If you do not specify a name for 
the index component, VSAM generates one (see "Defining a Cluster" 
for the format of the generated name). 

• ORDERED or UNORDERED: When ORDERED is specified, the first 
volume in the volser list (of the VOLUMES parameter) is to contain the 
index. Other volumes are to be available as overflow volumes. 
Otherwise, any volume specified in the volser list can be used for the 
index component. 

• OWNER: Identifies the index component's owner, when the owner 
identification is different from the owner of the alternate index as a 
whole. 

. REPLICATE or NOREPLICATE: Specifies whether the index 
component's records are to be repeated around the track. 

• REUSE or NOREUSE: Specifies whether the alternate index's index 
component is to be reusable. 

» SHAREOPTIONS: Specifies share options for the index component 
when it is opened as a separate VSAM object by the user's program. 

. STAGE, BIND, or CYLINDERFAULT: Specifies how the index 
component, stored on a mass storage volume, is to be staged. 

• UNIQUE or SUB ALLOCATION: Specifies whether the index 
component is to occupy exclusively a VSAM data space or share an 
existing data space with other VSAM objects. 

• VOLUMES: Identifies the volume that is to contain the index 
component, and identifies other volumes that can be used as overflow 
volumes for the index component. 

. WRITECHECK or NOWRITECHECK: Specifies whether the index 
component's records are to be checked by the direct-access device when 
they are written into the index. 

Restrictions are noted above with each parameter's description. All of the 
INDEX subparameters are described in more detail as parameters cf the 
alternate index as a whole. 



The catalog parameter allows you to supply the name and password of the 
catalog in which the alternate index is to be defined. When you specify 
CATALOG, you identify the catalog that contains the base-cluster's entry. 

CATALOG( catname [/ password ] ) 

identifies the catalog in which the alternate index is to be defined. The 
catalog also contains the base cluster's entry (see the RELATE parameter 
above). See "Order of Catalog Use: DEFINE" for information about the 
order in which a catalog is selected if the catalog's name is not specified. 

catname 

specifies the catalog's name. 
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\ password 

^ specifies the catalog's update or higher level password. If the catalog is 

password-protected, you must supply the catalog's update or higher 
level password. If no password is specified with the CATALOG 
parameter, VSAM asks the operator for the catalog's update password. 

If the catalog's volume is physically mounted, it is dynamically allocated. 
The volume must be mounted as permanently resident or reserved. 

If the base cluster's master password is not specified with the RELATE 
parameter, then the catalog's master password must be specified. 

Abbreviation: CAT 
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In this example, an alternate index is defined. An example for DEFINE 
CLUSTER illustrates the definition of the alternate-index's base cluster, 
EXAMPLE.KSDS2. A subsequent example illustrates the definition of a path, 
EXAMPLE.PATH, that allows you to process the base-cluster's data records 
using the alternate key to locate them. The alternate index, path, and base 
cluster are defined in the same catalog, AMASTCAT. 

//DEFAIX JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

DEFINE ALTERNATE INDEX - 

( NAME ( EXAMPLE. AIX) - 

RELATE ( EXAMPLE . KSDS 2 ) - 

MASTERPW(AIXMRPW) - 

UPDATEPW( AIXUPPW ) - 

KEYS( 3 0)- 

RECORDSIZE(40 50) - 

VOLUMES (VSERO 4) - 

CYLINDERS ( 3 1)- 

NONUNIQUEKEY - 

UPGRADE ) - 
CATALOG ( AMASTCAT/MCATUPPW ) 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DEFINE ALTERNATEINDEX command creates an alternate-index 
entry, a data entry, and an index entry to define the alternate index 
EXAMPLE.AIX. The DEFINE ALTERNATEINDEX command also 
obtains space for the alternate index from one of the VSAM data spaces on 
volume VSER04, and allocates three cylinders for the alternate index's use. 
Since the alternate index is being defined into a recoverable catalog, the 
catalog recovery volume will be dynamically allocated. The command's 
parameters are: 

• NAME, which specifies that the alternate-index's name is 
EXAMPLE.AIX. 

• RELATE, which identifies the alternate-index's base cluster, 
EXAMPLE.KSDS2. 

. MASTERPW and UPDATEPW, which specifies the alternate-index's 
master password, AIXMRPW, and update password, AIXUPPW. 

• KEYS, which specifies the length and location of the alternate key field in 
each of the base-cluster's data records. The alternate key field is the first 
three bytes of each data record. 

• RECORDSIZE, which specifies that the alternate-index's records are 
variable-length, with an average size of 40 bytes and a maximum size of 50 
bytes. 

• VOLUMES, which specifies that the alternate index is to reside on volume 
VSER04. This example assumes that the volume is already cataloged in the 
master catalog, AMASTCAT. 
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CYLINDERS, which specifies that three cylinders are allocated for the 
alternate-index's space. When the alternate index is extended, it is to be 
extended in increments of one cylinder. 

NONUNIQUEKEY, which specifies that the alternate key value might be 
the same for two or more data records in the base cluster. 

UPGRADE, which specifies that the alternate index is to be opened by 
VSAM and upgraded each time the base cluster is opened for processing. 

CATALOG, which specifies that the alternate index is to be defined in the 
master catalog, AMASTCAT. The example also supplies the master 
catalog's update password, MCATUPPW. 
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DEFINE CLUSTER 

When you define a cluster, you can specify attributes for the cluster as a 
whole and for the cluster's components. The general format of the DEFINE 
CLUSTER command is: 

DEFINE CLUSTER (parameters) - 

[DATA(parameters)] - 

[INDEX(parameters)] - 

[CATALOG(subparameters)] 
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CLUSTER 

(NAMEi entryname) 
{CYUNDERS(primary[h secondary]) | 

IBtECOttDSiprimary [b secondary ]) | 

TRACKSiprimary [ b secondary ])} 
VOLUMES( vo/jer[b volser,..]) 
[ATTEMVTSi number |2)] 
[AVTHOMLATlONientrypomtih string ])] 
[BUFFERSPACE(5ize)] 
[CODEicode)] 

[CONTROLINTERVALSIZE( size )] 
[CONTROLFWipassword)] 
[DESTAGEWAIT | NODESTAGEWAIT ] 
[ERASE I NOERASE ] 
[EXCEPnONEXIT( entrypoint )] 
[¥llM{dname)] 
[FREESPACE(CI-i7ercen/ 

{hCA-percent]\^Q)] 
[IMBED I NOIMBED ] 

[ INDEXED I NONINDEXED | NUMBERED] 
[KEYRANGES((/oM;A:eyb highkey) 

[( lowkey b highkey )...])] 
[Y^YSUength b offset \ 64 0)] 
[MASTEMFy^ {password )] 
\MODiElj{entryname [/password ] 

[ b catname {/password ]])] 
[ORDERED I UNORDERED ] 
iOW^ERiownerid)] 
[REABF\V{password)\ 
[RECORDSIZE( ai^rage b maximum )] 
[REPLICATE I NOREPLICATE ] 
[REUSE INOREUSE] 
[SHAREOPTIONS( crossregion 

[b crosssystem ] | ![ 3)] 
[SPANNED I NONSPANNED] 
[SPEED I RECOVERY ] 
[STAGE I BIND | CYLINDERFAULT] 
{i:0{date)\EORidays)] 
[UNIQUE I SUB ALLOCATION ] 
[VVliATEFV<f{password )] 
[WRITECHECK | NOWRITECHECK] ) 



(Continued on next page.) 
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[DATA 

([ATTEMPTS( number )] 

[ AUTHORIZATION( entrypoint [ b string ])] 

[BUFFERSPACEC size )] 

[CODEC co^e)] 

[CONTROLINTERVALSIZEC size )] 

[CONTROLPW(/>as5worrf )] 

[CYLINDERSCpr/ma/y [ b secondary ]) | 

RECORDSC/^nma/y [b secondary ]) | 

TRACKS(/?rimarK [ b secondary ])] 
[DESTAGEWAIT | NODESTAGEWATT] 
[ERASE 1 NOERASE] 
[EXCEPnONEXrrC entrypoint )] 
[nLE( rfname)] 

[FREESPACECCI-percenf [ b Ck- percent ])] 
[KEYRANGES((fowikeyb highkey) 

[( lowkey b highkey )...])] 
[KEYS(/eng//i b o//5er)] 
[MASTERPW(;?as5wor J )] 
[MODEL( entryname [/password ] 

[b catname [/password]])] 
[NAME( entryname )] 
[ORDERED I UNORDERED] 
[OVmERiownerid)] 
[W£,ADVVi {password )] 
[RECORDSIZE(awemge b maximum ) 
[REUSE I NOREUSE] 

[SHAREOPTIONSC crojsregwK [b crosssystem ])] 
[SPANNED I NONSPANNED] 
[SPEED I RECOVERY] 
[STAGE I BIND | CYLINDERFAULT] 
[UNIQUE I SUBALLOCATION] 
[UPDATEPWCposswor^ )] 
[VOLUMESC volser [b volser ...])] 
[WRITECHECKINOWRITECHECK] )] 



(Continued on next page.) 
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[INDEX 

([ATTEMPTS( number )] 

[AUTHORIZATION(e/i//7/7om/ [b string ])] 

[CODEC co^e)] 

[CONTROLINTERVALSIZEC 5ize )] 

[CONTROhFWipassword )] . 

[CYLINDERS(;7nmarv [ b secondary ]) | 
RECORDS(/Jn>narv [ b secondary ]) | 
TRACKSiprimary [ b secondary ])] 

[DESTAGEWAIT | NODESTAGEWAIT] 

[EXCEPnONEXIT( entrypoint )] 

[FILE(^nawe)] 

[IMBED I NOIMBED] 

[MASTERPW(/7a55wor J )] 

\MOiy£lj{entryname [/password] 
[ b catname {/password ]])] 

[NAME( entryname )] 

[ORDERED I UNORDERED] 

[OWNER( ownent/)] 

[READPWC/^osjwor^)] 

[REPLICATE I NOREPLICATE] 

[REUSE ! NOREUSE] 

[SHAREOPTIONS( cro5jreg/on [b crosssystem ])] 

[STAGE I BIND | CYLINDERFAULT] 

[UNIQUE I SUBALLOCATION] 

[\JFYi ATEVyf {password )] 

[VOLUMES( vo/5er[b volser..,])] 

[WRITECHECK | NOWRITECHECK] )] 

[CATALOG( catname [/password ])] 



DEFINE CLUSTER Parameters: Summary 



The parameters of the DEFINE CLUSTER command can be divided into 
required and optional parameters. 

The parameters which are required for all types of clusters are: 

• Entry type, which specifies that a cluster and its catalog entry are to be 
created (CLUSTER). 

• Name, which names the cluster (NAME). 

• Allocation, which specifies the amount of space to be allocated to the 
cluster and identifies the volume(s) that is to contain the cluster 
(VOLUMES and one of CYLINDERS, RECORDS, or TRACKS). You 
need not explicitly specify the allocation parameter if you specify the 
MODEL parameter. 

The parameters which are required for an entry-sequenced or relative-record 
cluster but are optional for a key-sequenced cluster are: 

e Type, which specifies the kind of data organization for the cluster 

(INDEXED,NONINDEXED, or NUMBERED). You need not explicitly 
specify the type parameter for a key-sequenced cluster. You need not 
explicitly specify the type parameter for an entry-sequenced or 
relative-record cluster if you specify the MODEL parameter. 
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The optional parameters are: 

• Model, which identifies an existing cluster entry that is to be used as a 
model for the cluster being defined (MODEL). 

• Allocation, which specifies 

- whether the cluster's data space is to be shared with other VSAM 
objects (SUB ALLOCATION or UNIQUE). 

- the name of the DD statement that describes the cluster's volume(s) 
(FILE). 

- the size of control intervals, records, and the user program's buffer area 
(CONTROLINTERVALSIZE, RECORDSIZE, and BUFFERSPACE). 

- how a cluster or component that is stored on a mass storage device is to 
be staged (STAGE, BIND, or CYLINDERFAULT). 

- whether the volume's are to be allocated in the order given with the 
VOLUMES parameter (ORDERED or UNORDERED). 

- whether the cluster is intended for temporary storage of data (REUSE 
or NOREUSE). 

- whether the cluster's records can cross control-interval boundaries 
(SPANNED or NONSPANNED). 

• Data integrity, which specifies 

- the name of a user-written I/O error routine (EXCEPTIONEXTT), 

- whether data records are to be overwritten with binary zeros when the 
cluster is deleted (ERASE or NOERASE). 

- whether the data records are to be checked when the direct-access 
device writes them into secondary storage (WRJTECHECK or 
NOWRITECHECK). 

- whether a cluster or component, stored on a mass storage volume, is to 
be destaged synchronously or asynchronously with respect to the user's 
program that closes it (DESTAGEWAIT or NODESTAGEWAIT). 

- whether space is to be preformatted when the data is initially loaded 
(RECOVERY or SPEED). 

• Protection, which 

- specifies passwords for the cluster (MASTERPW, CONTROLPW, 
UPDATEPW, and READPW). 

- identifies the cluster to a console operator without revealing the cluster's 
entry name (ATTEMPTS and CODE). 

- identifies a user-written-security- verification routine for additional 
authorization verification (AUTHORIZATION). 

- identifies the cluster's owner (OWNER). 

- specifies a retention period for the cluster (FOR or TO). 



Command Format 223 



• Parameters that apply only to the definition of a key-sequenced cluster, 
which specify 

- whether index records are to be repeated around the track of the index's 
direct-access device (REPLICATE or NOREPLICATE). 

- whether the index's sequence-set records are to be written adjacent to 
their data control areas (IMBED or NOIMBED). 

- whether the data records are to be divided by key among volumes 
(KEYRANGES). 

- the length and offset of the cluster's key field (KEYS). 

- the amount of free space to be left in control intervals and control areas 
when the data records are loaded (FREESPACE). 

• Components, which specifies attributes for the cluster's data and, for a 
key-sequenced cluster, index components that might differ from those 
attributes specified for the cluster as a whole or the attributes established 
for the cluster being used as a model (DATA and INDEX). 

• Catalog, which identifies the catalog in which the cluster is to be defined 
(CATALOG). 

DEFINE can be abbreviated: DEF. 



DEFINE CLUSTER Parameters 
Required Parameters 



CLUSTER 

specifies that a cluster is to be defined. CLUSTER is followed by the 
parameters specified for the cluster as a whole; these parameters are 
enclosed in parentheses and, optionally, are followed by the DATA and/or 
INDEX parameters and their subparameters, enclosed in parentheses. 

Abbreviation: CL 

NAME( entryname ) 

specifies the name of the entry (cluster or component) being defined. 
NAME must be specified for the cluster; it can optionally be specified for a 
data or index component. If no name is specified for the data or index 
component, a name is generated. Because the cluster, data component, and 
index component are individually named, each can be addressed. 

The name may contain from 1 through 44 alphameric characters (A 
through Z, and through 9), national characters (@, #, and $), and two special 
characters (the hyphen and the 12-0 overpunch). Names containing more than 
eight characters must be segmented by periods; one to eight characters may be 
specified between periods. The first character of any name or name segment 
must be either an alphabetic or a national character. If you specify the name in 
the format entryname(modifier), only that portion of the name preceding the 
left parenthesis will be used. The modifier enclosed in parentheses will be 
ignored. 
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CYLINDERSC primary [b secondary]) \ 
\ RECORDS( primary [b secondary ] ) | 

TRACKS( primary [b secondary]) 

specifies the amount of space to be allocated to the cluster from the 
volume's available space, when UNIQUE is specified, or from the available 
space of one of the volume's VSAM data spaces. If you specify 
RECORDS, the amount of space allocated is the minimum number of 
tracks that are required to contain the specified number of records. 
However, if you specify TRACKS or RECORDS and if the minimum 
number of tracks should exceed a cylinder, space is allocated in terms of 
cylinders. When UNIQUE is specified and the data component is to be 
contained on more than one volume, each volume can contain a maximum 
of 16 extents. 

When the data component is not divided into key ranges and more than 
one volume is specified, the primary amount of space is allocated only on 
the first volume when the component is defined. When the component 
increases in size so as to extend to additional volumes, the first allocation 
on each overflow volume is the primary amount. 

When KEYRANGES is specified and the data component is to be 
contained on more than one volume, the primary amount of space is 
immediately allocated on each volume required for the key ranges. If more 
than one key range is allocated on a single volume, the primary amount is 
allocated for each key range. 

secondary amounts can be allocated on all volumes available to contain 
parts of the cluster regardless of the key ranges. The primary and each 

^ secondary allocation must be able to be satisfied in 5 extents; otherwise 

/ your DEFINE or data set extension will fail. 

If you do not specify the MODEL parameters, you must specify one, and 
only one, of the following parameters: CYLINDERS, RECORDS, or 
TRACKS. You can specify the amount of space as a parameter of 
CLUSTER, as a parameter of DATA, or as a parameter of both DATA 
and INDEX. When a key-sequenced cluster is being defined and the space 
is specified as a parameter of: 

• CLUSTER, the amount specified is divided between the data and index 
components. The division algorithm is a function of control interval size, 
record size, device type, and other data set attributes. If the division 
results in an allocation for the data component which is not an integral 
multiple of the required control-area size, the data-component's 
allocation is rounded up to the next higher control-area multiple. This 
rounding may result in a larger total allocation for your cluster than 
which you specified. 

• DATA, the entire amount specified is allocated to the data component. 
An additional amount of space, depending on control-interval size, 
record size, device type, and other data set attributes, is allocated to the 
index component. 

When you specify UNIQUE, and the amount of space you specify for the 
data component of the cluster is not an even multiple of cylinder-size, 
VSAM rounds the allocation upward to a multiple of a cylinder. 

1^ To determine the exact amount of space allocated to each component, list 

f the cluster's catalog entry, using the LISTCAT command. 
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When you specify UNIQUE, and the cluster's data space is the first data 
space on a volume that belongs to a recoverable catalog, an additional 
amount of (the equivalent, in tracks, of) one cylinder is allocated for the 
recovery area data space. 

primary 

specifies the initial amount of space that is to be allocated to the cluster. 

secondary 

specifies the amount of space that is to be allocated each time the 
cluster extends, as a secondary extent. When secondary is specified, 
space for the cluster's data and index components can be expanded to. 
include a maximum of 123 extents. If the data space that contains (all or 
part of) the cluster cannot be extended because the cluster's secondary 
allocation amount is greater than the data-space's secondary allocation 
amount, VSAM buUds a new data space. The new data space's primary 
and secondary allocation amounts are equal to the cluster's secondary 
allocation amount. 

primary and secondary can be expressed in decimal (n), hexadecimal 
(X*n'), or binary (B'n') form. 

Abbreviations: CYL, REC, and TRK 

VOLUMES( volser [b voter ... ] ) 

specifies the volumes to contain the cluster or component. VOLUMES 
must be specified if you do not specify the MODEL parameter. It can be 
specified for the cluster as a whole. Alternatively, it can be specified as a 
parameter of DATA and, if the cluster is key-sequenced, as a parameter of 
INDEX. 

If the data and index components are to reside on different device types, 
VOLUMES must be specified as both a DATA and an INDEX parameter. 
If more than one volume is listed with a single VOLUMES parameter, the 
volumes must be of the same device type. In a system with the Mass 
Storage System, a cluster or component can be defined on a mass storage 
volume. 

A volume serial number may be repeated in the list only if the INDEXED 
and KEYRANGE parameters are specified. You may wish to do this in 
order to have more than one key range on the same volume. Even in this 
case, repetition is only valid if all duplicate occurrences are used for the 
primary allocation of some key range. 

volser 

is a 1 to 6 alphameric or national character volume serial number. 
Special characters you can specify are the comma [,], semicolon [;], 
parentheses [( and )], slash [/], asterisk [*], period [.], single quotation 
mark ['], ampersand [ & ], plus sign [+], hyphen [-], and equal sign [=]. 
Code a single quotation mark as two single quotation marks. 

If the volume serial number includes a special character, enclose volser 
in quotation marks. For example, you can specify 
VOLUMES('VOL*10' 'VOL"AB') to include volumes VOL* 10 and 
VOL'AB in the cluster's volume list. 
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The VOLUMES parameter interacts with other DEFINE CLUSTER 
parameters. You should take care to ensure that the volume(s) you specify 
for the cluster can satisfy the cluster's other attributes: 

. SUB ALLOCATION: If UNIQUE is not specified, the volume must 
contain VSAM data space. 

. KEYRANGES: If KEYRANGES and UNIQUE are specified, a VSAM 
data space is built and allocated for each key range on a separate 
volume. 

• ORDERED: If ORDERED is specified, the volumes are used in the 
order listed. If ORDERED and KEYRANGES are specified, there is a 
one-f or-one correspondence between the key ranges in the key-range 
list and the volumes in the volser list. 

• CYLINDERS, RECORDS, TRACKS: The volume(s) must contain 
enough unallocated space to satisfy the component's primary space 
requirement. 

• FILE: The volume information supplied with the DD statement(s) 
pointed to by FILE must be consistent with the information specified 
for the cluster and its components. 

• CATALOG: The data space on the volume must have been defined in 
the same catalog that the cluster is being defined in, and must be owned 
by the catalog. 

Abbremtion: VOL 



When a cluster is defined, you specify whether the data is to be indexed 
(key-sequenced), nonindexed (entry-sequenced), or numbered 
(relative-record). 

Certain parameters apply only to key-sequenced clusters, as noted in the 
description of each of these parameters. 

If you do not specify the data organization and you also do not specify the 
MODEL parameter, your cluster will default to key-sequenced (indexed). If 
you wish to define either an entry-sequenced or relative-record cluster, you 
must specify the NONINDEXED or NUMBERED parameter unless you 
specify the MODEL parameter. 

INDEXED I NONINDEXED | NUMBERED 

specifies the type of data organization that the cluster is to have. When a 
cluster is defined, you can specify whether the data organization is to be 
indexed (key-sequenced), sequential (entry-sequenced), or numbered 
(relative-record). The data organization you select must be consistent with 
other parameters you specify. 

INDEXED 

specifies that the cluster being defined is for key-sequenced data. If 
INDEXED is specified, an index component is automatically defined 
and cataloged. The data records can be accessed by key or by 
relative-byte address (RBA). See also the INDEX parameter. 

Abbreviation: IXD 
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NONINDEXED 

specifies that the cluster being defined is for entry-sequenced data. The 
data records can be accessed sequentially or by relative-byte address 
(RBA). 

Abbreviation: NIXD 

NUMBERED 

specifies that the cluster's data organization is for relative-record data. 
A relative-record cluster is similar to an entry-sequenced cluster, and 
has fixed-length records that are stored in slots. Each slot might or 
might not contain a data record. The data records are accessed by 
relative=record number (that is, slot number). 

Abbreviation: NUMD 



ATTEMPTS( number \ 2 ) 

specifies the maximum number of times the operator can try to enter a 
correct password in response to a prompting message. The number can be 
any number, through 7. If is specified, the operator is not prompted 
and is not allowed to enter a password from the console. 

number 

can be expressed in decimal (n), hexadecimal (X'n'), or binary (B'n') 
form. This parameter can be coded, but only has effect when the entry's 
master password is not null. A prompting message is issued only when 
the user has not already supplied the appropriate password. 

Note to TSO Users: At a TSO terminal, the logon password is checked first 
before the user is prompted to supply a password for the cluster. Checking 
the logon password counts as one attempt to obtain a password. If 
ATTEMPTS is not specified, the user has one attempt to supply the 
cluster's password because the default is 2. 

Abbreviation: ATT 

AUTHORIZATION( entrypoint [b string]) 

specifies that a user-security-verification routine (USVR) is available for 
additional security verification. When a protected cluster is accessed and 
the user supplies a correct password other than the cluster's master 
password, the USVR receives control. See OS/VS Virtual Storage Access 
Method (VSAM) Programmer's Guide for details on the USVR. 

If a USVR is loaded from an unauthorized library during Access Method 
Services processing, an abnormal termination will occur. See the section 
"Authorized Program Facility" in the chapter "Introduction." 

This parameter can be coded, but only has effect when the entry's master 
password is not null. 

entrypoint 

specifies the name of the user's-security-verification routine. 

The name can contain one to eight alphameric characters (A through Z, 
or through 9), national characters ((3), #, and $), or special characters 
(the hyphen and 12-0 overpunch). The first character must be an 
alphabetic or national character. 
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string 

specifies information to be passed to the user-security-verification 
routine when it receives control to verify authorization, and can contain 
1 to 255 EBCDIC characters. When the string contains a special 
character (that is, a comma [,], semicolon [;], blank [b], period [.], 
single quote ['], ampersand [ & ], plus sign [+], equal sign [=], hyphen 
[-], parenthesis [( or )], slash [/], or asterisk [*]), enclose the string in 
single-quotation marks (for example, AUTHORIZATION( entrypoint, 
'*DORIS*')). 

When the string contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, AUTHORIZATION( entrypoint, 
'*CA"ROL*')). 

You can code string in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
AUTHORIZATION( entrypoint, X'E2E4C5') is the same as 
AUTHORIZATION( entrypoint, SUE). The string can contain up to 
255 hexadecimal characters when expressed in this form, resulting in up 
to 128 bytes of information. 

Abbreviation: AUTH 

BUFFERSPACE( size ) 

specifies the minimum space to be provided for buffers. The buffer space 
size you specify helps VSAM determine the data-component's and 
index-component's control-interval size. If BUFFERSPACE is not coded, 
VSAM attempts to get enough space to contain two data component 
control intervals and, if the data is key sequenced, one index-component 
control interval. 

size 

is the amount of space to be provided for buffers, size can be expressed 
in decimal (n), hexadecimal (X'n'), or binary (B'n') form. The size 
specified cannot be less than enough space to contain two 
data-component control intervals and, if the data is key sequenced, one 
index control interval. If the specified size is less than VSAM requires 
for the buffers needed to run your job, VSAM terminates your DEFINE 
and provides an appropriate error message. 

Abbreviations: BUFSP or BUFSPC 

CODE( code ) 

specifies a code name for the entry being defined. If an attempt is made to 
access a password-protected entry without a password, the code name is 
used in a prompting message; the code enables the operator to be 
prompted for the password without disclosing the name of the entry. 

If CODE is not specified and an attempt is made to access a cluster or 
component that is password protected without supplying a password, the 
operator is prompted with the name of the entry. 

This parameter can be coded, but only has effect when the cluster's or 
component's master password is not null. A prompting message is issued 
only when the user hasn't already supplied the appropriate password. 



Command Format 229 



code 

can contain 1 to 8 EBCDIC characters. When the code contains a 
special character (that is, a comma [,], semicolon [;], blank [b], period 
[.], single quote ['], ampersand [ & ], plus sign [+], equal sign [=], 
hyphen [-], parenthesis [( or )], slash [/], or asterisk [*]), enclose the 
code m single-quotation marks (for example, CODEC*DORIS*')). 

When the code contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, CODE('*CA"ROL*')). 

You can code code in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
CODE(X'E2E4C5') is the same as CODE(SUE). 

CONTROLINTERVALSIZE( ste ) 

specifies the size of the control interval for the cluster or component. 

The size of the control interval depends on the maximum size of the data 
records and the amount of buffer space you provide. If the size you specify 
is not an integer multiple of 512 or 2048, VSAM selects the next higher 
multiple for your cluster's control-interval size. 

If CONTROLINTERVALSIZE is not coded, VSAM determines the size 
of control intervals. If you have not specified BUFFERS? ACE and the 
size of your records permits, VSAM uses the optimum size for the data 
component and 512 for the index component. 

size 

for a cluster's data component. 

The size of a data-control interval must be at least 7 bytes larger than 
the maximum record length if the data set does not have the SPANNED 
attribute. If the control interval specified is less than maximum record 
length plus the 7-byte overhead, then VSAM will increase the 
data-control interval size to contain the maximum record length plus the 
needed overhead. If the data set has the spanned attribute, the 
control-interval size can be less than the maximum record length. The 
sizes you can specify — between 512 and 32,768 bytes — are an integer 
multiple of 512 or 2048: 

CISZ = (n X 512) or (n x 2048) 

where n is a positive integer from 1 to 16 

size 

for a key-sequenced cluster's index component. 

You can specify the following values: 

CISZ = [512 I 1024 I 2048 | 4096] 

When you specify a size that is not a multiple of 512 or 2048, VSAM 
chooses the next higher multiple. 

Refer to the chapter "Optimizing VSAM's Performance" in OS/VS 
Virtual Storage Access Method (VSAM) Programmer's Guide for a 
discussion of the relationship between control interval size and physical 
block size. The discussion also includes restrictions that apply to control 
interval size and physical block size. 

Abbreviations: CISZ or CNVSZ 
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CONTROLPW( password ) 

specifies a control password for the entry being defined. The control 
password permits operations using control-interval access to read, write, 
and update control intervals that contain the cluster's records. 

If a read or update password is the only password specified for the object, 
it (the highest-level password) propagates upward and becomes the 
password for all higher unspecified levels. 

password 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [fe], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in sin^e-quotation marks (for 
example, CONTROLPWC*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, CONTROLPW('*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
CONTROLPW(X'E2E4C5') is the same as CONTROLPW(SUE). 

Abbreviation: CTLPW 

DESTAGEWATT | NQDESTAGEWATT 

specifies whether a cluster or its component that is stored on a mass 
storage volume is to be destaged synchronously or asynchronously with 
respect to the program that closes it. 

DESTAGEWAIT indicates that destaging is to be completed before 
VSAM returns control to the program that issued the CLOSE macro. 
VSAM can thus notify the program whether destaging was successful. 

NODESTAGEWAIT indicates that notification of unsuccessful destaging 
is to be made only by a message to the operator. 

When the cluster or component is not stored on a mass storage volume, the 
attribute is ineffective until the direct-access storage volume the cluster or 
component is stored on is converted to a mass storage volume (by way of 
the CONVERTV command, which is described in OS/VS Mass Storage 
System (MSS) Services: Reference Information). 

When one of these parameters is specified for the data component and the 
other parameter is specified for the index component, the components are 
destaged separately as specified, except when the sequence set of the index 
component is imbedded iii the data. In that case, the parameter specified 
for the index component applies to both components. 

Abbreviations: DSTGW and NDSTGW 

ERASE I NOERASE 

specifies whether the cluster's data component is to be erased when its 
entry in the catalog is deleted. If ERASE is specified, the data component 
is overwritten with binary zeros when its catalog entry is deleted. 

Abbreviations: ERAS and NERAS 



•Command Format 23 1 



EXCEPnONEXIT( entrypoint ) 

specifies the name of the user-written routine, called the exception exit 
routine, that receives control when an exceptional I/O error condition 
occurs during the transfer of data between your program's address space 
and the cluster's direct-access storage space. (An exception is any I/O 
error condition that causes a SYNAD exit to be taken.) The component's 
exception-exit routine is processed first, then the user's SYNAD-exit 
routine receives control. 

If an exception exit routine is loaded from an unauthorized library during 
Access Method Services processing, an abnormal termination will occur. 
See the section "Authorized Program Facility" in the chapter 
"Introduction." 

Abbreviation: EEXT 

FILE( dname ) 

specifies the name of the DD statement that identifies the devices and 
volumes to be used for space allocation. When you specify UNIQUE, 
FILE can identify the DD statement which identifies and allocates the 
volumes of the cluster. If more than one volume is specified, all volumes 
must be the same device type. If data and index components are to reside 
on different device types, FILE is specified as a parameter of DATA and 
INDEX so that separate DD statements can be referenced. 

When the cluster is defined in a recoverable catalog, and FILE is specified 
as a parameter of CLUSTER, the FILE parameter can identify the DD 
statement for all volumes on which space is to be allocated. When FILE 
refers to more than one volume of the same device type, the DD statement 
that describes the volumes cannot be a concatenated DD statement. When 
the cluster is cataloged in a recoverable catalog, the DD statement can be 
concatenated if the volumes are of different device types: part of the 
concatenated DD statement describes the cluster's or component's 
volume (s) of one device type; the other part of the DD statement describes 
the volume (s) of another device type. 

If the FILE parameter is not specified, the required volumes are 
dynamically allocated. If the cluster or. one of its components is unique, 
and if the FILE parameter is not specified and the volume (s) is physically 
mounted, the volume(s) identified with the VOLLIMES parameter is 
dynamically allocated. The volume(s) must be mounted as permanently 
resident or reserved. 

The DD statement you specify must be in the form: 

/ /ddname DD UMT=( devtype [ , unitcount ] ), 
// \Olj=S¥R={volserl,volser2,volser, ...),... 

FREESPACE( CI -percent [b CA-percent]\ 0) 

specifies the amount of space that is to be left free when the cluster is 
loaded and after any split of control intervals (Cl-percent) and control 
areas (CA-percent). The amount of empty space in the control interval and 
control area is available for data records that are updated and inserted after 
the cluster is initially loaded. This parameter applies only to key-sequenced 
clusters. 

The amounts are specified as percentages. Cl-percent translates into a 
number of bytes that is equal to, or slightly less than, the percentage value 
of Cl-percent. CA-percent translates into a number of control intervals 
that is equal to, or less than, the percentage value of CA-percent. 
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CI -percent and CA-percent, which must be equal to or less than 100, can 
be expressed in decimal (n), hexadecimal (X'n'), or binary (B'n') fonn. 

When you specify FREESPACE(100 100), one data record is placed in 
each control interval used for data and one control interval in each control 
area is used for data (that is, one data record is stored in each control area 
when the data set is loaded). When no FREESPACE value is coded, the 
default specifies that no free space be reserved when the data set is loaded. 

Abbreviation: FSPC 

IMBED I NOIMBED 

specifies whether the sequence set (the lowest level of the index) is to be 
placed with the data component. If IMBED is coded, each sequence-set 
record for each control area is written as many times as it will fit on the 
first track adjacent to the control area. This parameter applies only to 
key-sequenced clusters. 

The IMBED | NOIMBED parameter interacts with the 
REPLICATE I NOREPLICATE parameter in determining the physical 
attributes of the index of the cluster. These index attributes can be used in 
the following combinations: 

• The sequence set records are adjacent to the data control areas, and 
only the sequence set records are replicated (IMBED and 
NOREPLICATE). 

• The sequence set records are adjacent to the data control intervals, and 
all levels of index records are replicated (IMBED and REPLICATE). 

• All index records are together, and all index records are replicated 
(REPLICATE and NOIMBED). 

• All index records are together, and no index records are replicated 
(NOREPLICATE and NOIMBED). 

For some applications specifying index options can improve the 
application's performance. 

See OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide 
for information on how the index's optional attributes affect performance. 

Abbreviations: IMBD and NIMBD 

KEYRANGES(( lowkey h highkey ) 

[ ( lowkey b highkey )...]) 

specifies that portions of key-sequenced data are to be placed on different 
volumes. Each portion of the data is called a key range. This parameter 
applies only to key-sequenced clusters. 

The maximum number of key ranges is 123. Key ranges must be in 
ascending order, and are not allowed to overlap. A gap can exist between 
two key ranges, but you are not allowed to insert records whose keys are 
within the gap. 
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The KEYRANGES parameter interacts with other DEFINE CLUSTER 
parameters. You should take care to ensure that, when you specify 
KEYRANGES, the cluster's other attributes can be satisfied. 

• VOLUMES: There should be as many volume serial numbers in the 
volser list as there are key ranges. When a volume serial number is 
duplicated in the volser list, more than one key range is allocated space 
on the volume. When more than one key range is contained on a 
volume, UNIQUE cannot be coded for the cluster's data component. 

When there are more volumes in the volser list than there are key 
ranges, the excess volumes are used for overflow records from any key 
range without consideration for key-range boundaries. 

When there are fewer volumes in the volser list than there are key 
ranges, the excess key ranges are allocated on the last volume 
specified — UNIQUE cannot also be specified. 

• UNIQUE: When UNIQUE is specified, each key range resides on its 
own volume in" its own VSAM data space. Other key ranges for the 
cluster cannot also reside on the volume. 

• ORDERED: There is a one-for-one correspondence between the 
volumes in the volser list and the key ranges: the first volume on the 
volume list contains the first key range, the second volume contains the 
second key range, and so on. If a volume cannot be allocated in the 
order specified by the volser list, your cluster definition job terminates 
with an error message. 

• KEYS: The length of the key values must not exceed the key length 
specified in the KEYS parameter. 

Keys can contain 1 to 64 characters; 1 to 128 hexadecimal characters if 
coded as X' lowkey ' b X' highkey '. All EBCDIC characters are allowed. 
Keys consisting of characters must be enclosed in single quotation marks if 
they contain commas, semicolons, blanks, parentheses, or slashes. A single 
quotation mark within a key must be coded as two single quotation marks 
if the key is enclosed in single quotation marks. 

lowkey 

specifies the low key of the key range. If lowkey is shorter than the 
actual keys, it will be padded on the right with binary zeros. 

highkey 

specifies the high key of the key range. If highkey is shorter than the 
actual keys, it will be padded on the right with binary ones. 

Abbreviation: KRNG 

KEYS( length b offset | 64 ) 

specifies information about the key field of a key-sequenced data set's data 
records. This parameter applies only to key-sequenced clusters. 

length b offset 

specifies the length of the key and its displacement (in bytes) from the 
beginning of the record. The sum of length + offset cannot exceed the 
length of the shortest record. 

The length of the key can be from 1 through 255 bytes, length and 
offset can be expressed in decimal (n), hexadecimal (X'n'), or binary 
(B'n') form. 
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The key field of the cluster's index is called the prime key to distinquish 
it from other key fields, called alternate keys. See DEFINE 
ALTERNATEINDEX for more details on how to specify alternate keys 
for a cluster. 

KEYS cannot be specified when you define an entry-sequenced cluster 
or a relative-record cluster. When the data record is allowed to span 
control intervals, the record's key field must be within the part of the 
record that is in the first control interval. 

MASTERPWC password ) 

specifies a master password for the entry being defined. The master 
password allows all Access Method Services operations against the cluster 
entry and its data and index entries. The master password allows the user's 
program to access the cluster's contents without restriction. For more 
details on how passwords can be used, see "Data Security and Protection." 
The AUTHORIZATION, CODE, and ATTEMPTS parameters have no 
effect unless the entry has a master password associated with it. If 
MASTERPW is not specified, the highest-level password specified 
becomes the password for all higher levels. 

password 

is a one- to eight- EBCDIC character password. 

When the password contains a special character (that is, a conmia [,], 
semicolon [;], blank [fe], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, MASTERPWC*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, MASTERPWC*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
MASTERPW(X'E2E4C5') is the same as MASTERPW(SUE). 

Abbreviation: MRPW 

MODEL ( entryname [ / password ] 

[ b catname [ / password ]] ) 

specifies that an existing entry is to be used as a model for the entry being 
defined. You can use an existing cluster's entry as a model for the 
attributes of the cluster being defined. For details about how a model is 
used, see "How to Use One Object as a Model for Another Object." 

You may use some attributes of the model and override others by explicitly 
specifying them in the definition of the cluster or component. If you do not. 
want to add or change any attributes, you need specify only the entry-type 
(cluster, data, or index) of the model to be used and the name of the entry 
to be defined. 

When you use a cluster entry as a model for the cluster, the model-cluster's 
data and index entries are used as models for the to-be-defined cluster's 
data and index components, unless another entry is specified with the 
MODEL parameter as a subparameter of DATA or INDEX. 
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entryname 

specifies the name of the cluster or component entry to be used as a 
model. 

password 

specifies a password. If the model entry is password protected and it is 
cataloged in a password-protected catalog, you must supply the read- 
(or higher-level) password of either the model entry or its catalog. If 
both passwords are supplied, the catalog's password is used. 

If you are not specifying new protection attributes for the cluster (that 
is, the model's passwords and protection attributes are being copied), 
you must supply the master password of either the model entry or its 
catalog. 

catname 

names the model-entry's catalog. You identify the catalog that contains 
the model entry for either of these cases: 

• You specify the catalog's password instead of the model-entry's 
password. 

• The model-entry's catalog is not identified with a JOBCAT or 
STEPCAT DD statement, and is not the master catalog. 

If the catalog's volume is physically mounted, it is dynamically allocated. 
The volume must be mounted as permanently resident or reserved. See 
"Order of Catalog Use: DEFINE" for information about the order in 
which a catalog is selected when the catalog's name is not specified, 

ORDERED I UNORDERED 

specifies whether volumes are to be used in the order in which they were 
listed in the VOLUMES parameter. If KEYRANGES is also specified, all 
of the records within the range specified by the first low-key/high-key pair 
are placed on the first volume specified in VOLUMES; all of the records 
within the second range are placed on the second volume; etc. If it is 
impossible to allocate volumes in the given order and ORDERED is 
specified, the command is terminated. 

Abbreviations: ORD and UNORD 

OWNER( ownerid ) 

specifies the identification of the cluster's owner. 

ownerid 

can contain 1 to 8 EBCDIC characters. 

When the ownerid contains a special character (that is, a comma [,], 
semicolon [;], blank [h], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [—], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the ownerid in single-quotation marks (for 
example, OWNERC*DORIS*').) 

When the ownerid contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, OWNER('*CA"ROL*')). 

You can code ownerid in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
OWNER(X'E2E4C5') is the same as OWNER(SUE). 

Note to TSO Users: If the owner is not identified with the OWNER 
parameter, the TSO user's userid becomes the ownerid. 
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READPW( password ) 

specifies a read password for the entry being defined. The read password 
permits read operations against the cluster's data records. 

password 

is a one- to eight- EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [fe], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, READPW('*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, READPW('*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
READPW(X'E2E4C5') is the same as READPW(SUE). 

Abbreviation: RDPW 

RECORDSIZE( average b maximum | default ) 

specifies the average and maximum lengths, in bytes, of the records in the 
data component. 

RECORDSIZE can be specified as a parameter of either CLUSTER or 
DATA. 

average and maximum are integer values and can be expressed in decimal 
(n), hexadecimal (X'n'), or binary (B'n') form. The minimum record size 
that you can specify is 1 byte. For nonspanned records, the maximum 
recordsize + 7 cannot exceed the data-component's control interval size 
(that is, the maximum nonspanned record size, 32,761, + 7 equals the 
maximum data-component control interval size, 32,768). For spanned 
records , the maximum record size cannot exceed the number of control 
intervals per control area x (control interval size less ten), as calculated by 
VSAM. When you specify a record size that is larger than one control 
interval, you must also specify spanned records (SPANNED). 

You can identify the records as fixed-length by specifying the same value 
for average and maximum. If NUMBERED is also specified, the records 
must be fixed-length (that is, average equals maximum). 

When your records are fixed-length, you can use the following formula to 
find a control-interval size that contains a whole number (n) of records: 

CISZ = (n X RECSZ) + 10 
or 

n = (CISZ - 10) -r RECSZ 
where: 

• n is the number of fixed-length records in a control interval, and is a 
positive integer. 

• CISZ is the control interval size (see also the 
CONTROLINTERVALSIZE parameter). 
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• RECSZ is the average record size. 

default 

When SPANNED is specified, the default is RECORDSIZE(4086 
32600). Otherwise, the default is RECORDSIZE(4089 4089). 

Caution: When you specify RECORDS, you should ensure that: 

REC(sec) X RECSZ(avg) > RECSZ(max) 

where: 

• REC(sec) is the secondary space allocation quantity, in records. 

• RECSZ(avg) is the average record size (default = 4086 or 4089 bytes). 

• RECSZ(max) is the maximum record size (default = 4089 or 32600 
bytes). 

When the SPANNED record size default prevails (32600 bytes), the 
secondary allocation quantity should be at least 8 records. 

If you plan to copy your cluster using either the EXPORT or EXPORTRA 
command, you should be aware of the restiction in maximum record length 
imposed by these commands. Refer to the sections "Moving Entries" and 
"Copying a Catalog Entry From the Catalog Recovery Area" for details of 
this restriction. 

Abbreviation: RECSZ 

REPLICATE I NOREPLICATE 

specifies whether each index record is to be written on a track as many 
times as it will fit. When you specify REPLICATE, rotational delay is 
reduced and performance is improved. However, the cluster's index usually 
requires more direct-access device space. This parameter applies only to 
key-sequenced clusters. 

Refer to the description of the IMBED | NOIMBED parameter for a 
discussion of the relationship between IMBED | NOIMBED and 
REPLICATE I NOREPLICATE. 

Abbreviations: REPL and NREPL 

REUSE I NOREUSE 

specifies whether the cluster can be opened again and again as a 
temporary, or reusable, cluster (that is, with its high-used RBA set to zero 
when you open it with an ACB which specifies the RESET attribute). 
REUSE allows you to create an entry-sequenced, key-sequenced, or 
relative-record workfile. 

When you create a reusable cluster, you cannot build an alternate index to 
support it. Also, you cannot create a reusable cluster with key ranges (see 
the KEYRANGE parameter) or with its own data space (see the UNIQUE 
parameter). Reusable data sets may be multivolumed and are restricted to 
sixteen physical extents per volume. 

Abbreviations: RUS and NRUS 
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SHAREOPnONS( crossregion [ b crosssystem ] I 1 3 ) 

specifies how a component or cluster can be shared among users. See 
OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide for 
a description of data set sharing. 

Unless you specify sharing optons, the cluster cannot be shared. 

crossregion 

specifies the amount of sharing allowed among regions. Independent job 
steps in an operating system can access a VSAM data set concurrently. 
To share a data set, each user must specify DISP=SHR in the data set's 
DD statement. The values that can be specified are: 

1 

specifies that the data set can be shared by any number of users for 
read processing, or the data set can be accessed by only one user for 
read and write processing. With this option, VSAM ensures complete 
data integrity for the data set. 

specifies that the data set can be accessed by any number of users for 
read processing and it can also be accessed by one user for 
processing. With this option, VSAM ensures write integrity by 
obtaining exclusive control for a control interval when it is to be 
updated. If a user desires read integrity, it is his responsibility to use 
the ENQ and DEQ macros appropriately to provide read integrity for 
the data his program obtains. 

specifies that the data set can be fully shared by any number of users. 
With this option, each user is responsible for maintaining both read 
and write integrity for the data his program accesses. User programs 
that ignore the write integrity guideUnes can cause VSAM program 
checks, lost or inaccessible reccords, uncorrectabble data set failures, 
and other unpredictable results. This option places heavy 
responsibility on each user sharing the data set. 

specifies that the data set can be fully shared by any number of users 
and buffers used for direct processing are refreshed for each request. 
This option requires your program to use the ENQ and DEQ macros 
to maintain data integrity while sharing the data set. Improper use of 
the ENQ macro can cause problems similar to those described under 
SHAREOPTION 3. 

crosssystem 

specifies the amount of sharing allowed among systems. Job steps of 
two or more OS/VS operating systems can gain access to the same 
VSAM data set regardless of the disposition specified in each step's DD 
statement for the data set. To get exclusive control of the data set's 
volume, a task in one system issues the RESERVE macro. The level of 
cross-system sharing allowed by VSAM applies only in a multiple 
operating system envh-onment. The values that can be specified are: 

1 

Reserved 
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4 



Reserved 

3 

specifies that the data set can be fully shared. With this option, each 
user is responsible for maintaining both read and write integrity for 
the data his program accesses. User programs that ignore 
write-integrity guidelines can cause VSAM program checks, 
uncorrectable data set failures, and other unpredictable results. This 
option places heavy responsibiUty on each user sharing the data set. 

4 

specifies that the data set can be fully shared. Buffers used for direct 
processing are refreshed for each request. This option requires that 
you use the RESERVE and RELEASE macros to maintain data 
integrity while sharing the data set. Writing is limited to PUT-update 
and PUT-insert processing that does not change the high-used RBA 
if your program opens the data set with DISP= SHR. Data set 
integrity cannot be maintained unless all jobs accessing the data set in 
a cross-system environment specify DISP=SHR. Improper use of the 
RESERVE macro can cause problems similar to those described 
under SHAREOPTION 3. 

The assistance VSAM provides each user to ensure data integrity in a 
shared environment is: 

• Each PUT request results in the appropriate buffer(s) being written 
immediately to the VSAM cluster's direct-access device space (that is, 
the buffer in the user's address space that contains the new or updated 
data record, and the buffers that contain new or updated index records 
when the user's data is key-sequenced.) 

• Each GET request results in all of the user's input buffers being 
refreshed. That is, each buffer's contents (each data and index buffer 
being used by the user's program) is retrieved from the VSAM cluster's 
direct access device. 

To ensure integrity you should be sure that share options specified at the 
DATA and INDEX levels are the same. 

Additional information about shared data can be found in OS/VS Virtual 
Storage Access Method (VSAM) Programmer's Guide. 

Abbreviation: SHR 

SPANNED I NONSPANNED 

specifies whether a data record is allowed to cross control-interval 
boundaries. When the maximum length of a data record (as specified with 
RECORDSIZE) is larger than a control interval, the record can be 
contained on more than one control interval. To ensure that you want this 
to happen, specify SPANNED. (This allows VSAM to select a control 
interval size that is optimum for the direct-access device.) Otherwise, 
VSAM would select a larger control interval size that accommodates your 
largest record. 

When a data record which is larger than a control interval is put into a 
cluster that allows spanned records, the first part of the record completely 
fills a control interval. Subsequent control intervals are filled until the 
record is written into the cluster. Unused space in the record's last control 
interval is not available to contain other data records. 
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I Abbreviations: SPND and NSPND 

^ SPEED I RECOVERY 

specifies whether storage allocated to the data component is to be 
Preformatted before records are inserted. SPEED | RECOVERY applies 
only to initial loading. 

When RECOVERY is specified, the data component's control areas are 
written with records that indicate end-of-file. When a data record is written 
(during the initial load) into a control interval, it is always followed by a 
record that identifies the just-written record as the last record in the 
cluster. If the initial load fails, you can resume loading data records after 
the last correctly-written data record (because an end-of-file indicator 
identifies it as the last record — that is, no more data records follow). 

When SPEED is specified, the data component's space is not preformatted. 
Its space might contain data records from a previous use of the space, or it 
might contain binary zeros — its contents are unpredictable. If the initial 
load fails, you must load the data records again from the beginning 
(because VSAM is unable to determine where your last correctly-written 
record is — VSAM cannot find a valid end-of-file indicator when it searches 
your data records). 

When you specify RECOVERY, your initial load takes longer because the 
control areas are written initially with end-of-file indicators, and again with 
your data records. When you specify SPEED, your initial load is quicker. 

Abbreviation: RCVY 

v^ STAGE I BIND | CYLINDERFAULT 

specifies how a cluster or component that is stored on a mass storage 
volume is to be staged. 

STAGE 

indicates that the cluster or component is to be staged from mass 
storage to a direct access storage staging drive when the cluster or 
component is opened. If the cluster or component cannot be staged at 
open time because of heavy staging activity of other objects, data is 
staged as a processing program needs it. 

BIND 

indicates that the cluster or component is not only to be staged, but also 
to be bound — that is, retained on the direct-access storage staging drive 
until it is closed. If the cluster or component cannot be staged at open 
time because of heavy staging activity of other objects, data is staged as 
a processing program needs it. 

CYLINDERFAULT 

indicates that the cluster or component is not to be staged when it is 
opened, but that data from it is to be staged as a processing program 
needs it. 

Abbreviation: CYLF 

When the cluster or component is not stored on a mass storage volume, the 
attribute is ineffective until the direct access storage volume the cluster or 
component is stored on is converted to a mass storage volume (by way of 
1,^^ the CONVERTV command, which is described in OS/VS Mass Storage 

y System (MSS) Services: Reference Information). 
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When one of these parameters is specified for the data component and 
another parameter is specified for the index component, the components 
are staged separately as specified, except when the sequence set of the 
index component is imbedded in the data. In that case, the parameter 
specified for the index component applies to both components. 

T0( date ) | FOR( days ) 

specifies the retention period for the cluster being defined. If neither TO 
nor FOR is specified, the cluster can be deleted at any time. 

TO( date ) 

specifies the date, in the form yyddd, where yy is the year and ddd is the 
number (001 through 365) of the day, through which the cluster being 
defined is to be kept. 

FOR( days ) 

specifies the number of days for which the cluster being defined is to be 
kept. The maximum number that can be specified is 9999. If the number 
specified is through 1830, the cluster is retained for the number of 
days specified; if the number is between 1831 and 9999, the cluster is 
retained through the year 1999. 

days 

can be expressed in decimal (n), hexadecimal (X'n'), or binary (B'n') 
form. 

UNIQUE I SUB ALLOCATION 

specifies whether the cluster's components are allocated space of their own 
or whether a portion of previously defined VSAM data space is to be used 
for each component. 

If UNIQUE is specified, the components of the cluster are allocated space 
separately. Their names appear in the VTOC of the volume(s) within a 
format- 1 DSCB. 

If SUBALLOCATION is specified, the name of the data space, not of the 
component, appears in the VTOC. If SUBALLOCATION is coded, a data 
space must exist on the volume on which the cluster or components are to 
reside. When UNIQUE is specified as a parameter of CLUSTER, a data 
space is built and allocated to each component of the cluster. 

The space-allocatioii attribute interacts with other DEFINE CLUSTER 
parameters. You should take care to ensure that the attribute you specify 
for the cluster is consistent with other attributes: 

• REUSE: You cannot specify REUSE when you specify UNIQUE for a 
cluster or its components. 

• KEYRANGES: When UNIQUE is specified, a data space is built and 
allocated for each key range. Each key range is on a separate volume. 

. VOLUMES: When UNIQUE is not specified, VSAM data space must 
exist on the volume that is to contain the cluster's component. When 
UNIQUE is specified, and more than one volume is specified, VSAM 
must already own all the volumes except the first. If there is no VSAM 
space on a volume, you must execute a DEFINE SPACE CANDIDATE 
before your DEFINE UNIQUE. 

Abbreviations: UNQ and SUBAL 
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UPDATEPW( password ) 

specifies an update password for the entry being defined. The update 
password permits read and write operations against the cluster's data 
records. 

If a read password is the only password specified for the object (that is, it 
is the highest-level password), it propagates upward and becomes the 
password for all higher levels. If you specify a higher-level password and 
do not specify an update password, the update password is null. 

password 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, UPDATEPWC*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, UPDATEPW('*CA"ROL*')). 

You can code password in Hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
UPDATEPW(X'E2E4C5') is the same as UPDATEPW(SUE). 

Abbreviation; UPDPW 

WRITECHECK | NOWRITECHECK 

specifies whether the cluster or component is to be checked by a machine 
action called write check when a record is written into it. If 
WRITECHECK is specified, a record is written and then read, without 
data transfer, to test for the data check condition. 

Abbreviations: WCK and NWCK 
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Attributes can be specified separately for the cluster's data and index 
components. 

DATA( options ) 

specifies attributes of the data component of the cluster. You can specify 
separate attributes for the data component of any type of cluster (that is, 
entry-sequenced, key-sequenced, and relative-record). 

Except for name, space allocation, and protection attributes, attributes 
specified as parameters of DATA override the same attributes specified as 
parameters of CLUSTER. Attributes specified as parameters of DATA 
also override the same attributes of a model cluster's data entry. 
Parameters that can be specified for the cluster's data component are: 

. ATTEMPTS, AUTHORIZATION, and CODE: Specifies protection 
attributes for the data component when it is opened as a separate 
VSAM object by the user's program. 

• BUFFERSPACE: Specifies the amount of buffer space that the user's 
program is to provide from its address space when the program opens 
the data component as a separate VSAM object. 
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CONTROLINTERVALSIZE: Specifies the size of the data 
component's control interval The sizes you can specify are: 

CISZ = (n X 512) or (n X 2048) 

where n is a positive integer from 1 to 16. 

CYLINDERS, RECORDS, or TRACKS: You can specify an amount of 
space to be allocated to the data component. When you specify space as 
a parameter of DATA, however, you cannot also specify space for the 
cluster as a whole. See the description of CYLINDERS | RECORDS | 
TRACKS as parameters of CLUSTER. 

DESTAGEWAIT or NODESTAGEWAIT: Specifies whether the data 
component, stored on a mass storage volume, is to be destaged 
synchronously or asynchronously with respect to the user's program that 
closes it. 

ERASE or NOERASE: Specifies whether the data records are to be 
erased when the cluster is deleted. 

EXCEPTIONEXIT: Identifies an exception exit routine for the cluster's 
data component. 

FILE: Names the DD statement that describes a direct access device 
and volume that is to contain the data component. When more than one 
volume is to contain the data component, all volumes for that 
component must be the same device type. 

FREESPACE: Specifies the amount of space that is to be left free 
during loading and after any split of control intervals and control' areas. 
This parameter is valid only for a key-sequenced cluster. 

KEYRANGES: Specifies that portions of the data component of a 
key-sequenced cluster are to be put on different volumes, and specifies 
the boundaries of each key range. 

KEYS: Describes the key field of a key-sequenced cluster's data record. 

MASTERPW, CONTROLPW, UPDATEPW, and READPW: Specifies 
passwords for the data component when it is opened as a separate 
VSAM object by the user's program. 

MODEL: Identifies a data entry that is to be used as a model for the 
data component only. 

NAME: Names the data component. If you do not specify a name for 
the data component, VSAM generates one (see "Defining a Cluster" for 
the format of the generated name). 

ORDERED or UNORDERED: When ORDERED is specified, the 
volumes listed with the VOLUMES parameter are allocated in the order 
listed. 

OWNER: Identifies the data component's owner, when the owner is 
different from the owner of the cluster as a whole. 

RECORDSIZE: Specifies the average and maximum sizes of the 
cluster's data records. 

REUSE or NOREUSE: Specifies whether the data component is to be 
reusable. 
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\ e SHAREOPTIONS: Specifies share options for the data component 

when it is opened as a separate VSAM object by the user's program. 

• SPEED or RECOVERY: Specifies whether the data control intervals 
are to be preformatted with the end-of-file indicator before data records 
are inserted. 

. SPANNED or NONSPANNED: Specifies whether a data record is 
allowed to cross control interval boundaries. 

. STAGE, BIND, or CYLINDERFAULT: Specifies whether the data 
component, stored on a mass storage volume, is to be staged. 

. UNIQUE or SUB ALLOCATION: Specifies whether the data 
component is to occupy a separate VSAM data space or share an 
existing data space with other VSAM objects. 

• VOLUMES: Identifies the volume that is to contain the data 
component, and identifies other volumes that can be used as overflow 
volumes for the data component. All volumes must be of the same 
device type. 

. WRITECHECK or NOWRITECHECK: Specifies whether the data 
records are to be checked by the direct access device when they are 
written into the data component. 

DATA and its subparameters can be specified for any type of cluster. All 
of the DATA subparameters are described in more detail as parameters of 
the cluster as a whole. Certain of the above subparameters apply only to 

the data component of a key-sequenced cluster. 

j 

/ INDEX( options ) 

specifies attributes of the index component of a key-sequenced cluster. 
Except for name, space allocation, and protection attributes, attributes 
specified as parameters of INDEX override the same attributes specified as 
parameters of CLUSTER. Attributes specified as parametei-s of INDEX 
also override the same attributes of a model cluster's index entry. 

Parameters that can be specified for the cluster's index component are: 

. ATTEMPTS, AUTHORIZATION, and CODE: Specifies protection 
attributes for the index when it is opened as a separate VSAM object by 
the user's program. 

. CONTROLINTERVALSIZE: Specifies the size of the index's control 
interval. The sizes you can specify are: 512, 1024, 2048, or 4096 bytes. 

. CYLINDERS, RECORDS, or TRACKS: You can specify an amount of 
space to be allocated to the index component. When you specify one of 
the space-quantity parameters as a parameter of INDEX, you must also 
specify a space-quantity parameter as a parameter of DATA. You 
cannot also specify a quantity of space for the cluster as a whole. 

. DESTAGEWAIT or NODEST AGE WAIT: Specifies whether the index 
component, stored on a mass storage volume, is to be destaged 
synchronously or asynchronously with respect to the user's program that 
closes it. 

• EXCEPTIONEXIT: Identifies an exception exit routine for the index 
f\ component. 
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• FILE: The DD statement describes a direct access device that is to 
contain the index. When more than one volume is to contain the index 
component, all volumes for that component must be the same device \ 
type. 

• IMBED or NOIMBED: Specifies vi^hether the sequence set records are 
to be written adjacent to the data. 

. MASTERPW, CONTROLPW, UPDATEPW, and READPW: Specifies 

passwords for the index when it is opened as a separate VSAM object 
by the user's program. 

• MODEL: Identifies an index entry that is to be used as a model for the 
index component only. 

• NAME: Names the index component. If you do not specify a name for 
the index component, VSAM generates one (see "Defining a Cluster" 
for the format of the generated name). 

. ORDERED or UNORDERED: When ORDERED is specified, the first 
volume in the volser list (of the VOLUMES parameter) is to contain the 
index. Other volumes are to be available as overflow volumes. 
Otherwise, any volume specified in the volser list can be used for the 
index. 

• OWNER: Identifies the index's owner, when the owner identification is 
different from the owner of the cluster as a whole. 

. REPLICATE or NOREPLICATE: Specifies whether the index's 
records are to be repeated around the track. 

• REUSE or NOREUSE: Specifies whether the index component is to be 
reusable. \ 

• SHAREOPTIONS: Specifies share options for the index when it is 
opened as a separate VSAM object by the user's program. 

• STAGE, BIND, or CYLINDERFAULT: Specifies how the index 
component, stored on a mass storage volume, is to be staged. 

. UNIQUE or SUB ALLOCATION: Specifies whether the index is to 
occupy a separate VSAM data space or share an existing data space 
with other VSAM objects. 

• VOLUMES: Identifies the volume that is to contain the index, and 
identifies other volumes that can be used as overflow volumes for the 
index. All volumes must be of the same device type. 

. WRITECHECK or NOWRITECHECK: Specifies whether the index 
records are to be checked by the direct-access device when they are 
written into the index. 

INDEX and its subparameters can be specified only for a key-sequenced 
cluster. Other restrictions are noted with each parameter's description. All 
of the INDEX subparameters are described in more detail as parameters of 
the cluster as a whole. 



246 0S/VS2 Access Method Services 



DEFINE CLUSTER 

Catalog (Cluster) 

The catalog parameter is used to supply the name and password, when 
required, of the catalog in which the cluster is to be defined. 

CATALOG! catname [ / password\ ) 

identifies the catalog in which the cluster is to be defined. See "Order of 
Catalog Use: DEFINE" for information about the order in which catalogs 
are used. 

catname 

specifies the name of the catalog in which the entry is to be defined. 

password 

specifies the catalog's password. If the catalog is password protected, 
you must supply the update- or higher-level password. If no password is 
specified, VSAM asks the operator for the correct password. 

If the catalog's volume is physically mounted, it is dynamically allocated. 
The volume must be mounted as permanently resident or reserved. 

Abbreviation: CAT 
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DEFINE CLUSTER Examples 
Define a Key-Sequenced Cluster: Example 1 



In this example, a key-sequenced cluster is defined. The DATA and INDEX 
parameters are specified and the cluster's data and index components are 
explicitly named. This example assumes that VSAM data space exists on 
volume VSER02. It also assumes that an alias name D40 has been defined for 
the catalog D27UCAT1. This naming convention causes D40.MYDATA to 
be cataloged in D27UCAT1. 

//DEFCLU2 JOB 

//STEP1 EXEC PGM='IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

DEFINE CLUSTER - 

(NAME(D40.MYDATA) - 
VOLUMES! VSERO 2 ) - 
RECORDS( 1000 500 ) ) - 
DATA - 

(NAME(KSDATA) - 
KEYS( 15 0)- 
RECORDSIZE( 250 250) - 
FREESPACE( 20 10 ) - 
BUFFERSPACE( 25000 ) ) - 
INDEX - 

(.NAME(KSINDEX) - 
IMBED) - 
CATALOG (D27UCAT1/UPPWD27 ) ' 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DEFINE CLUSTER command builds a cluster entry, a data entry, and 
an index entry to define the key-sequenced cluster D40.MYDATA. The 
parameters specified for the cluster as a whole are: 

• NAME, which specifies that the cluster's name is D40.MYDATA. 

• VOLUMES, which specifies that the cluster is to reside on volume 
VSER02. 

• RECORDS, which specifies that the cluster's space allocation is 1,000 data 
records. When the cluster is extended, it is extended in increments of 500 
records. After the space is allocated, VSAM calculates the amount required 
for the index and subtracts it from the total. 

In addition to the parameters specified for the cluster as a whole, DATA and 
INDEX subparameters specify values and attributes that apply only to the 
cluster's data or index component. The parameters specified for the data 
component of D40.MYDATA are: 

• NAME, which specifies that the data component's name is KSDATA. 

• KEYS, which specifies that the length of the key field is 1 5 bytes and that 
the key field begins in the first byte (byte 0) of each data record. 

• RECORDSIZE, which specifies fixed-length records of 250 bytes. 

• BUFFERSPACE, which specifies that a minimum of 25000 bytes must be 
provided for I/O buffers. A large area for I/O buffers can help to improve 
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access time with certain types of processing. For example, with direct 
processing if the high-level index can be kept in virtual storage, access time 
is reduced. With sequential processing, if enough I/O buffers are available, 
VSAM can perform a read-ahead thereby reducing system overhead and 
minimizing rotational delay. 

• FREESPACE, which specifies that 20 percent of each control interval and 
10 percent of each control area are to be left free when records are loaded 
into the cluster. After the cluster's records are loaded, the free space can 
be used to contain new records. 

The parameters specified for the index component of D40.MYDATA are: 

• NAME, which specifies that the index-component's name is KSINDEX. 

• IMBED, which specif ies that sequence-set index records are to be placed in 
the data component's control areas (the sequence-set records will be 
replicated automatically). 

The parameter which provides the catalog's password is: 

• CATALOG, which specifies the catalog name and its update password. 
This parameter would not be necessary if ( 1 ) the catalog was not password 
protected and (2) D40 has been defined as the catalog's alias. 



Define a Key-Sequenced Cluster and an Entry-Sequenced Cluster: Example 2 



In this example, two VSAM clusters are defined. The first DEFINE command 
defines a key-sequenced VSAM cluster, D40.EXAMPLE.KSDSL The second 
DEFINE command defines an entry-sequenced VSAM cluster, 
D50.EXAMPLE.ESDSL In both examples it is assumed that alias names, 
D40 and D50, have been defined for user catalogs D27UCAT1 and 
D27UCAT2, respectively, and that neither user catalog is password 
protected. This example assumes that VSAM data space that can contain the 
data sets already exists on volumes VSER02 and VSER03. 

//DEFCLU2 JOB . . . • 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

DEFINE CLUSTER - 

( NAME (D40. EXAMPLE. KSDS 1 ) - 

MODEL (D40.MYD ATA) - 

VOLUMES (VSERO 2 ) - 

NOIMBED ) 

DEFINE CLUSTER - 

( NAME (D50. EXAMPLE. ESDS 1 ) - 
RECORDS! 100 500 ) - 
RECORDSIZE( 250 250) - 
VOLUMES (VSERO 3 ) - 
NON INDEXED ) 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 
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The first DEFINE command builds a cluster entry, a data entry, and an index 
entry to define the key-sequenced cluster D40.EXAMPLE.KSDS1. Its 
parameters are: 

• NAME, which specifies the name of the key-sequenced cluster, 
D40.EXAMPLE.KSDS1. The cluster will be defined in the user catalog for 
which D40 has been established as an alias. 

• MODEL, which identifies D40.MYDATA as the cluster to use as a model 
for D40.EXAMPLE.KSDS1. The attributes and specifications of 
D40.MYDATA that are not otherwise specified with the DEFINE 
command's parameters are used to define the attributes and specifications 
of D40.EXAMPLE.KSDS1. D40.MYDATA is located in the user catalog 
for which D40 has been established as an alias. 

• VOLUMES, which specifies that the cluster is to reside on volume 
VSER02. 

• NOIMBED, which specifies that space is not to be allocated for 
sequence-set control intervals within the data-component's physical 
extents. 

The second DEFINE command builds a cluster entry and a data entry to 
define an entry-sequenced cluster D50.EXAMPLE.ESDS1. Its parameters 
are: 

• NAME, which specifies the name of the entry-sequenced cluster, 
D50.EXAMPLE.ESDS1. The cluster will be defined in the user catalog for 
which D50 has been estabhshed as an alias. 

• RECORDS, which specifies that the cluster's space allocation is 100 
records. When the cluster is extended, it is entended in increments of 500 
records. 

• RECORDSIZE, which specifies that the cluster's records are fixed-length 
(the average record, size equals the maximum record size) and 250 bytes ' 
long. 

• VOLUMES, which specifies that the cluster is to reside on volume 
VSER03. 

• NONINDEXED, which specifies that the cluster is to be an 
entry-sequenced cluster. 



Define a Key-Sequenced Cluster (In a Unique Data Space): Example 3 



In this example, a key-sequenced cluster is defined. The cluster is unique; that 
is, it is the only cluster in a VSAM data space. 

//DEFCLU3 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//V0L4 DD VOL=SER=VSER04,UNIT=2314,DISP=OLD 

//SYSIN DD * 

DEFINE CLUSTER - 

(NAME (ENTRY) - 

RECORDSIZE( 80 80 ) - 

FILE(V0L4) - 

KEYS( 10 10 ) - 

VOLUMES( VSER04 ) - 

UNIQUE - 

CYLINDERS ( 5 10) ) - 
CATALOG ( MYCAT ) 
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The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DEFINE CLUSTER command builds a cluster entry, a data entry, and 
an index entry to define the key-sequenced 'duster ENTRY. The DEFINE 
CLUSTER command also allocates a data space and allocates it for the 
cluster's exclusive use. The command's parameters are: 

• NAME, which specifies the cluster's name is ENTRY. 

• RECORDSIZE, which specifies that the records are fixed-length, 80 byte 
records. 

• FILE, which specifies the name of a DD statement that describes the 
cluster's volume and causes it to be mounted. The volume must be 
mounted so that VSAM can record the format- 1 DSCBs of the 
key-sequenced cluster in the volume's VTOC. If FILE is not specified, the 
volume is dynamically allocated. 

• KEYS, which specifies that the length of the key field is 10 bytes and that 
the key field begins in the 1 1th byte (byte 10) of each data record. 

. VOLUMES and UNIQUE, which specify that ENTRY is to reside alone in 
a data space on volume VSER04. Access Method Services will create two 
data spaces for the cluster: one for the data component, and one for the 
index. Both data spaces are to be on volume VSER04. This example 
assumes that volume VSER04 has enough available space to contain the 
new data space. This example also assumes that either the volume's entry is 
in the MYCAT catalog or that volume VSER04 is not owned by a VSAM 
catalog at the beginning of the job. 

• CYLINDERS, which specifies that five cylinders are allocated for the 
cluster's data space. When the cluster's data or index component is 
extended, the component is to be extended in increments of ten cylinders. 

• CATALOG, which specifies the name of the catalog into which the cluster 
will be defined. In this example, MYCAT is not password protected and 
will be dynamically allocated. 



Define a Relative-Record Cluster: Example 4 



In this example, a relative-record cluster is defined. The cluster is suballocated 
(that is, it can reside in a VSAM data space with other VSAM objects). 
Volume VSER04 does not have to be mounted or allocated at this time. 

//DEFCLU4 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

DEFINE CLUSTER - 

( NAME ( EXAMPLE . RRDS 1 ) - 

RECORDSIZEC 100 100) - 

VOLUMES! VSER04) - 

TRACKS! 10 5)- 

NUMBERED ) - 
CATALOG! AMASTCAT/MCATUPPW ) 
/* 
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The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DEFINE CLUSTER command builds a cluster entry and a data entry to 
define the relative-record cluster EXAMPLE. RRDSl in the master catalog. 
The DEFINE CLUSTER command also obtains space for the cluster from 
one of the VSAM data spaces on volume VSER04, and allocates ten tracks 
for the cluster's use. The command's parameters are: 

• NAME, which specifies that the cluster's name is EXAMPLE.RRDSL 

• RECORDSIZE, which specifies that the records are fixed-length, 100 byte 
records. Average and maximum record length must be equal for a 
relative-record data set. 

• VOLUMES, which specifies that the cluster is to reside on volume 
VSER04. This example assumes that the volume is already cataloged in the 
master catalog, AMASTCAT. 

• TRACKS, which specifies that ten tracks are allocated for the cluster's 
space. When the cluster is extended, it is to be extended in increments of 5 
tracks. 

• NUMBERED, which specifies that the cluster's data organization is to be 
relative-record. This parameter overrides the INDEXED default. 

• CATALOG, which supplies the master-catalog's update password, 
MCATUPPW. 



Define a Reusable Entry-Sequenced Cluster: Example 5 



In this example, a reusable entry-sequenced cluster is defined. The cluster can 
be used as a temporary data set. Each time the cluster is opened, its high-used 
RBA can be reset to zero. The cluster is suballocated (that is, it can reside in 
a VSAM data space with other VSAM objects). 

//DEFCLU5 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

DEFINE CLUSTER ^ 

( NAME ( EXAMPLE. ESDS 2 ) - 

RECORDSIZE( 2500 3000 ) - 

SPANNED - 

VOLUMES! VSER03 ) - 

CYLINDERS! 2 1)- 

NONINDEXED - 

REUSE - 

MASTERPW( ESD2MRPW ) - 

UPDATEPW( ESD2UPPW ) ) - 
CATALOG! D27UCAT2/UPDD27 ) 
/* 

The job control language statement is: ' 

• SYSPRINT DD, which is required in all Access Method Services jobs. The 
SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DEFINE CLUSTER command builds a cluster entry and a data entry to 
define the entry-sequenced cluster EXAMPLE.ESDS2. The DEFINE 
CLUSTER command also obtains space for the cluster from one of the Class 1 
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VSAM data spaces on volume VSER03, and assigns ten tracks for the 
cluster's use. VSER03 does not have to be mounted or allocated at this time. 
The command's parameters are: 

• NAME, which specifies that the cluster's name is EXAMPLE.ESDS2. 

• RECORDSIZE, which specifies that the records are variable-length, with 
an average size of 2500 bytes and a maximum size of 3000 bytes. 

• SPANNED, which specifies that data records can cross control-interval 
boundaries. 

• VOLUMES, which specifies that the cluster is to reside on volume 
VSER03. This example assumes that the volume is already cataloged in the 
user catalog, D27UCAT2. 

• CYLINDERS, which specifies that two cylinders are allocated for the 
cluster's space. When the cluster is extended, it is to be extended in 
increments of one cylinder. 

• NONINDEXED, which specifies that the cluster's data organization is to 
be entry-sequenced. This parameter overrides the INDEXED parameter. 

• REUSE, which specifies that the cluster is to be reusable. Each time the 
cluster is opened, its high-used RBA can be reset to zero and it is 
effectively an empty cluster. 

• M ASTER? W and UPDATEPW, which specifies the master password, 
ESD2MRPW, and the update password, ESD2UPPW, for the cluster. 

• CATALOG, which specifies that the cluster is to be defined in a user 
catalog, D27UCAT2. The example also supplies the user-catalog's master 
password, UPDD27. 
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Define a Key-Sequenced Cluster: Example 6 



In this example, a key-sequenced cluster is defined. In other examples, an 
alternate index is defined over the cluster, and a path is defined that relates 
the cluster to the alternate index. The cluster, its alternate index, and the path 
entry are all defined in the same catalog, AMASTCAT. 



//DEFCLU6 


JOB 


//STEP1 


EXEC PGM=IDCAMS 


//SYSPRIN 


T DD SYSOUT=A ' 


//SYSIN 


DD * 


DEFINE CLUSTER - 



( NAME ( EXAMPLE . KSDS 2 ) - 
DATA - 

( MASTERPW( DAT2MRPW ) - 

UPDATEPW( DAT2UPPW ) - 

READPW( DAT2RDPW ) - 

RECORDS(500 100) - 

EXCEPTIONEXIT( DATEXIT ) - 

ERASE - 

FREESPACE( 20 10) - 

KEYS( 6 4)- 

RECORDSIZE( 80 1 00 ) - 

VOLUMES! VSER04) > - 
INDEX - 

( MASTERPW( IND2MRPW ) - 

UPDATEPW( IND2UPPW ) - 

READPW( IND2RDPW ) - 

RECORDS! 300 300) - 

IMBED - 

VOLUMES! VSER04) ) - 
CATALOG! AMASTCAT/MCATUPPW ) 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DEFINE CLUSTER command builds a cluster entry, a data entry, and 
an index entry to define the key-sequenced cluster EXAMPLE.KSDS2. The 
DEFINE CLUSTER command also obtains space for the cluster from one of 
the VSAM data spaces on volume VSER04, and allocates space separately for 
the cltister's data and index components. Since the cluster is being defined 
into a recoverable catalog, the catalog recovery area will be dynamically 
allocated on VSER04. 

The command's parameter that applies to the cluster is: 

• NAME, which specifies that the cluster's name is EXAMPLE.KSDS2. 

The command's parameters that apply only to the cluster's data-component 
are enclosed in the parentheses following the DATA keyword: 

. MASTERPW, UPDATEPW, and READPW, which specify the data 
component's master password, DAT2MRPW, update password, 
DAT2UPPW, and read password, DAT2RDPW. 

• RECORDS, which specifies that an amount of tracks equal to at least 500 
records is to be allocated for the data component's space. When the data 
component is extended, it is to be extended in increments of tracks equal 
to 100 records. 
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• EXCEPTIONEXIT, which specifies the name of the exception exit 
routine, DATEXIT that is to be processed if an I/O error occurs while a 
data record is being processed. 

• ERASE, which specifies that the cluster's data is to be erased (overwritten 
with binary zeros) when the cluster is deleted. 

• FREESPACE, which specifies the amounts of free space to be left in the 
data component's control intervals (20 percent) and the control areas (10 
percent of the control intervals in the control area) when data records are 
loaded into the cluster. 

• KEYS, which specifies the location and length of the key field in each data 
record. The key field is the sixth (byte 5) through ninth bytes of each 
record. 

• RECORDSIZE, which specifies that the cluster's records are 
variable-length, with an average size of 80 bytes and a maximum size of 
100 bytes. 

• VOLUMES, which specifies that the cluster is to reside on volume 
VSER04. This example assumes that the volume is already cataloged in the 
master catalog, AMASTCAT, 

The command's parameters that apply only to the cluster's index component 
are enclosed in the parentheses following the INDEX keyword: 

. MASTERPW, UPDATEPW, and READPW, which specifies the 
index-component's master password, IND2MRPW, update password, 
IND2UPPW, and read password, IND2RDPW. 

• RECORDS, which specifies that an amount of tracks equal to at least 300 
records is to be allocated for the index-component's space. When the index 
component is extended, it is to be extended in increments of tracks equal 
to 300 records. 

• IMBED, which specifies that the index's sequence set records are to be 
placed in the data-component's control areas (the sequence set records will 
be replicated automatically). 

• VOLUMES, which specifies that the index component is to reside on 
volume VSER04. 

The CATALOG parameter supplies the catalog's update password. 
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Define an Entry-Sequenced Cluster 

(The Cluster has a Generic Name): Example 7 



In this example, two entry-sequenced clusters are defined. Each has the 
generic name "GENERIC.*.BAKER", where the asterisk (*) is replaced with 
a simple name that uniquely identifies each cluster. 

//DEFCLU4 JOB 

//STEP 1 EXEC PGM=IDCAMS 

//STEPCAT DD ' DSNAME=D27UCAT1 , DISP=OLD 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

DEFINE CLUSTER - 

(NAME (GENERIC. A. BAKER) - 

VOLUMES( VSER02 ) - 

RECORDS ( 100 100 ) - 

RECORDSIZE( 80 80 ) - 

NONINDEXED ) - 
CATALOG( D27UCAT1/MRPWD27 ) 

DEFINE CLUSTER - 

(NAME (GENERIC. B.BAKER) - 
MODEL( GENERIC. A. BAKER D27UCAT1)) - 
CATALOG ( D27UCAT1/MRPWD27 ) 
/* 

The job control language statements are: 

• STEPCAT DD, which makes a catalog available for this job step: 
D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The first DEFINE CLUSTER command defines an entry-sequenced cluster, 
GENERIC. A.BAKER. Its parameters are: 

• NAME, which specifies the name of the entry-sequenced cluster, 
GENERIC.A.BAKER. 

• VOLUMES, which specifies that the cluster is to reside on volume 
VSER02. 

• RECORDS, which specifies that the cluster's space allocation is 100 
records. When the cluster is extended, it is extended in increments of 100 
records. 

• RECORDSIZE, which specifies that the cluster's records are fixed-length 
(the average record size equals the maximum record size) and 80 bytes 
long. 

• NONINDEXED, which specifies that the cluster is entry-sequenced. 

• CATALOG, which specifies that the cluster is to be defined in the 
D27UCAT1 catalog. The master password of D27UCAT1 is MRPWD27. 

The second DEFINE CLUSTER command uses the attributes and 
specifications of the previously defined cluster, GENERIC.A.BAKER, as a 
model for the to-be-defined cluster, GENERIC.B.BAKER. Its parameters 
are: 

• NAME, which specifies the name of the entry-sequenced cluster, 
GENERIC.B.BAKER. 
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MODEL, which identifies GENERIC. A.BAKER, cataloged in user catalog 
D27UCAT1, as the cluster to use as a model for GENERIC.B.BAKER. 
The attributes and specifications of GENERIC.A.BAKER that are not 
otherwise specified with the DEFINE command's parameters are used to 
define the attributes and specifications of GENERIC.B.BAKER. 

CATALOG, which specifies that the cluster is to be defined in the 
D27UCAT1 catalog. The master password of D27UCAT1 is MRPWD27. 
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DEFINE GENERATIONDATAGROUP 



The format of the DEFINE command when it is used to define a generation 
data group is: 



DEFINE 


GENERATIONDATAGROUP 




iN\ME(entryname ) 




UMTTilimit) 




[EMPTY 1 NOEMPTY] 




[OWNERiownerid)] 




[SCRATCH 1 NOSCRATCH] 




[TO{date)\FORidays)] ) 




[CATALOG( catname [/password ])] 



DEFINE may be abbreviated: DEF. 



DEFINE GENERA TIONDA TA GROUP Parameters 



Required Parameters 



GENERATIONDATAGROUP 

specifies that a generation-data-group entry is to be defined. 

Abbreviation: GDG 

NAME( entryname ) 

specifies the name of the generation data group that is being defined. The 
name may consist of 1 through 35 alphameric characters (A through Z, and 
through 9), national characters (@, #, and $), and two special characters 
(the hyphen and the 12-0 overpunch). If the name is greater than eight 
characters, it is specified as a qualified name. A qualified name is 
segmented by periods; one to eight characters can be specified between 
periods. The first character of any name or name segment must be either 
an alphabetic or national character. 

LIMIT( limit ) 

specifies the maximum number, from 1 to 255, of generation data sets that 
can be associated with the generation data group to be defined, number can 
be expressed in decimal (n), hexadecimal (X'n'), or binary (B'n') form. 

Abbreviation: LIM 



Optional Parameters 



I 



EMPTY I NOEMPTY 

specifies what action is to be taken when the maximum number of 
generation data sets has been reached for the generation data group and 
another generation data set is to be cataloged. The disposition of the 
data-set's DSCB in the volume's VTOC is determined with the 
SCRATCH I NOSCRATCH parameter. 

EMPTY 

specifies that all the generation data sets are to be uncataloged when the 
limit is reached (that is, each data set's nonVSAM entry is automatically 
deleted from the catalog). 
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Abbreviation: EMP 

NOEMPTY 

specifies that only tlie oldest generation data set is to be uncataloged 
when the limit is reached. 

Abbreviation: NEMP 

OWNER( ownerid ) 

specifies the identification of the owner of the generation, data group being 
defined. The ownerid may contain one to eight EBCDIC characters. The 
ownerid must be enclosed in single quotation marks if it contains a comma, 
semicolon, blank, parenthesis, or slash. If a single quotation mark appears 
within ownerid, it must be coded as two single quotation marks when the 
ownerid is enclosed in single quotation marks. Ownerid may be coded in 
hexadecimal form, where two hexadecimal characters represent one 
EBCDIC character. If ownerid is specified in hexadecimal, it must be 
preceded by X and be enclosed in single quotation marks. If Access 
Method Services is being used interactively with TSO to define a 
generation data group, and OWNER is not specified, the TSO userid is the 
default ownerid. 

SCRATCH I NOSCRATCH 

specifies whether a generation data set's DSCB is to be deleted from the 
volume's VTOC when the data set is uncataloged (that is, when its entry is 
deleted from the catalog automatically, as a result of 
EMPTY I NOEMPTY, or specifically, as a result of a user-issued DELETE 
request). The user can override the SCRATCH | NOSCRATCH attribute 
when he issues the DELETE command. 

SCRATCH 

specifies that the generation data-set's DSCB is to be deleted from the 
volume's VTOC when it is uncataloged. Direct-access device space 
management (DADSM) removes the data set's DSCB from the VTOC, 
erases the data-set's space on the volume, and makes the space available 
to other system users. The generation data set ceases to exist. 

Abbreviation: SCR 

NOSCRATCH 

specifies thai the generation data set's DSCB is not to be removed from 
the volume's VTOC when it is uncataloged. The data set's DSCB in the 
volume's VTOC is intact and is used to locate the data set. The data set 
can no longer be accessed through the catalog. However, your program 
can process the data set as it processes any other nonVSAM data 
sets — that is, by using a JCL DD statement to describe the data set and 
allocate it. 

Abbreviation: NSCR 

TO( date ) | FOR( days ) 

specifies the retention period for the generation data group being defined. 

TO( date ) 

specifies the date, in the form yyddd, where yy is the year and ddd is the 
number (001 through 365) of the day, through which the generation 
data group being defined is to be kept. 
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FOR( days ) 

specifies the number of days for which the generation data group being 
defined is to be kept. This value can be expressed in decimal, 
hexadecimal, or binary. If it is expressed in hexadecimal or binary, it 
must be preceded by X or B and be enclosed in single quotation marks. 
The maximum number that can be specified is 9999. If the number 
specified is through 1830, the generation data group is retained for the 
number of days specified; if the number is between 1831 and 9999, the 
generation data group is retained through the year 1999. If neither TO 
nor FOR is specified, the generation data group can be deleted at any 
time. 

Catalog (Generation Data Group) 

CATALOG( cat name [b password ]) 

identifies the catalog in which the generation data group is to be defined. If 
the catalog's volume is physically mounted, it is dynamically allocated. The 
volume must be mounted as permanently resident or reserved. See "Order 
of Catalog Search: DEFINE" for information about the order in which a 
catalog is selected when the catalog's name is not specified. 

cainame 

specifies the name of the catalog. 

password 

specifies the catalog's password. If the catalog is password protected, 
you must supply the update- or higher-level password. 

Abbreviation: CAT 
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DEFINE GENERATIONDATAGROUP Example 

Define a Generation Data Group and a Generation Data Set 
Within It: Example 1 



In this example, a generation data group is defined in the master catalog. 
Next, a generation data set is defined within the generation data group by 
using JCL statements. 

//DEFGDG JOB ... - 

//STEP1 EXEC PGM=IDCAMS 

//GDGMOD DD DSNAME=GDG01 , DISP=( ,KEEP ) , 

// SPACE=(TRK,( 0) ),UNIT=2314,VOL=SER=VSER03, 

// DCB=(RECFM=FB,BLKSIZE=2000,LRECL=100) 

//SYSPRINT DD " SYSOUT=A ' 

//SYSIN DD * 

DEFINE GENERATIONDATAGROUP - 

(NAME(GDG0 1 ) - 

EMPTY - 

NOSCRATCH - 

LIMIT(255) ) 
/* 

//STEP2 EXEC PGM=IEFBR14 

//GDGDD1 DD DSNAME=GDG01 ( +1 ) , DISP=( NEW, CATLG ) , 

// SPACE= ( TRK ,(10,5)), VOL=SER=VSER0 3 , 

// UNIT=2314 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

/* 

The job control language statements are: 

• GDGMOD DD, which describes the generation data group. When the 
scheduler processes the DD statement, no space is allocated to GDGOl. 

The model DSCB must exist on the generation data group's catalog \ 

volume. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

Because no catalog was specified in a CATALOG parameter or with a 
JOBCAT or STEPCAT DD statement, VSAM assumes all entries built for 
this command sequence are to be cataloged in the master catalog. 

The DEFINE GENERATIONDATAGROUP command defines a generation 
data group base catalog entry, GDGOl. Its parameters are: 

• NAME, which specifies the name of the generation data group, GDGOl. 
Each generation data set in the group will have the name 

GDGOl. GxxxxVyy, where "xxxx" is the generation number and "yy" is 
the version number. 

• EMPTY, which specifies that all data sets in the group are to be 
uncataloged by VSAM when the group contains the maximum number of 
data sets (as specified by the LIMIT parameter and one more generation 
data set is added to the group). 

• NOSCRATCH, which specifies that, when a data set is uncataloged, its 
DSCB is not to be removed from its volume's VTOC. Therefore, even if a 
data set is uncataloged, its records can be accessed when it is allocated to a 
job step with the appropriate JCL DD statement. 



262 OS/VS2 Access Method Services 



DEHNE GENERATIONDATAGROUP 

e LIMIT, which specifies that the maximum number of generation data sets 
in the group is 255. The LIMIT parameter is required. 

The second step, STEP2, is used to allocate space and catalog a generation 
data set in the newly defined generation data group. Its job control statements 
are: 

• GDGDDl DD, which specifies a generation data set in the generation data 
group. 

• SYSPRINT DD, which is required in all job steps. The SYSPRINT DD 
statement identifies the output device to which messages to the 
programmer are to be sent. 
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DEFINE NONVSAM 



DEFINE NONVSAM 



The format of the DEFINE command when it is used to define a nonVSAM 
data set is: 



DEFINE 



NONVSAM 

( N AME( entryname ) 

DEVICETYPES( devtype [ b devtype ...]) 

VOLUMES( wiser [ b wiser ...]) 

[FILESEQUENCENUMBERSC number [ b number ...])] 

{OVmESL{o\merid)\ 

{TO{date)\¥OK{days)] ) 

[CATALOGC catname {/password ])] 



DEFINE may be abbreviated: DEF. 



DEFINE NONVSAM Parameters 



Required Parameters 



1 



NONVSAM 

specifies that a nonVSAM data set is to be defined. 

Abbreviation: NVSAM 

NAME( entryname ) 

specifies the name of the nonVSAM data set being defined. The entryname 
is the name that appears in the catalog; it is the name used in all future 
references to the data set. The entryname must be unique within the 
catalog in which it is defined. 

Relative generation numbers (that is, GDGname(+l)) cannot be used with 
the entryname when you use the DEFINE NONVSAM command to 
catalog a generation data set and attach it to a generation data group. You 
identify a generation data set with its generation-data-group name 
(GDGname) followed by the data set's generation and version numbers: 
NAME(GDGname.GxxxxVyy). 

The name may consist of 1 through 44 alphameric characters (A through 
Z, and O.through 9), national characters (@, #, and $), and two special 
characters (the hyphen and the 12-0 overpunch, X'CO'). Names containing 
more than eight characters must be segmented by periods; one to eight 
characters may be specified between periods. The first character of any 
name or name segment must be either an alphabetic or national character. 

DEVICETYPES( devtypes [ b devtype ... ] ) 

is a required parameter that specifies the device types of the volumes 
containing the nonVSAM data set being defined. If the nonVSAM data set 
resides on different device types, the device types must be specified in the 
same order as the volume serial numbers listed in the VOLUMES 
parameter. 

You can specify a device type for any device that is supported by your VS2 
system. You can specify a generic device type (that is, 3330, 2314, etc.) or 
a specific unit address (that is, 121, 247, etc.). You can specify an esoteric 
device type (for example, SYSDA or TAPE) only if it has been established 
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Optional Parameters 



in the system device name table during system generation. See the 
discussion of the SCRATCH | NOSCRATCH option of the DELETE 
command for a restriction on deleting data sets which have been defined 
with an esoteric device type. 

Abbreviation: DEVT 

VOLUMESC volser [ b volser ... ] ) 

specifies the volumes to contain the nonVSAM data set. In a system with 
the Mass Storage System, a nonVSAM data set can be defined on a mass 
storage volume. You can specify more than one volume serial number if 
the data set resides on many volumes. If the data set resides on magnetic 
tape and more than one file belongs to the data set on a single tape volume, 
you must repeat the volume's serial number in order to maintain a 
one-to-one correspondence between the volume serial numbers and the file 
sequence numbers. 

For example, if your nonVSAM data set is contained in the first three files 
of magnetic tape volume TAPE 10, you specify: 

DEVICETYPES( 2400 2400 2400) - 
VOLUMES (TAPE 10 TAPE 10 TAPE10) - 
FILESEQUENCENUMBERS( 1 2 3)- 

volser 

can contain 1 to 6 EBCDIC characters. 

When the volser contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [-f-], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the volser in single-quotation marks (for 
example, VOLUMESC*DORIS')). 

When the volser contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, VOLUMESC*CA"ROL')). 

You can code volser in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
VOLUMES(X*E2E4C5') is the same as VOLUMES(SUE). 

Abbreviation: VOL 



FILESEQUENCENUMBERS( number [b number ... ] ) 

specifies the file sequence number of the nonVSAM data set being defined. 
This number indicates the position of the file being defined with respect to 
other files of the tape. If the data set spans volumes, the file sequence 
number on each volume must be specified. The numbers must be specified 
in the same order as the volumes in the VOLUMES parameter. 

For example, if your nonVSAM data set is contained in the first three files 
of magnetic tape volume TAPE 10, you specify: 

DEVICETyPES(2400 2400 2400) - 
VOLUMES (TAPE 10 TAPE 10 TAPE10) - 
FILESEQUENCENUMBERS( 12 3)- 

number 

is a file sequence number, number can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n') form. 

Abbreviation: FSEQN 
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OWNER( ownerid ) 

specifies the identification of the nonVSAM data set. 

ownerid 

can contain 1 to 8 EBCDIC characters. When the ownerid contains a 
special character (that is, a comma [,], semicolon [;], blank [b], period 
[.], single quote ['], ampersand [ & ], plus sign [+], equal sign [=], 
hyphen [-], parenthesis [( or )], slash [/], or asterisk [*]), enclose the 
ownerid in single-quotation marks (for example, OWNER('*DORIS*'). 

When the ownerid contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, OWNER('*CA"ROL*')). 

You can code ownerid in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
OWNER(X'E2E4C5') is the same as OWNER(SUE). 

If Access Method Services is being used interactively with TSO to define a 
nonVSAM data set, and OWNER is not specified, the TSO userid is the 
default ownerid. 

TO( date ) I FOR( days ) 

specifies the retention period for the nonVSAM data set being defined. 
The nonVSAM data set is not automatically deleted when the expiration 
date is reached. When you do not specify a retention period, the 
nonVSAM data set can be deleted at any time. 

The maximum number that can be specified for days is 9999. If the 
number specified is through 1 830, the retention period is the number of 
days specified. If the number specified is between 1831 and 9999, the 
retentioiThperiod is through the year 1999. 

FOR( days ) 

specifies the number of days for which the nonVSAM data set is to be 
kept before it is allowed to be deleted, days can be expressed in decimal 
(n), hexadecimal (X'n'), or binary (B'n') form. 

TO( date ) 

specifies the date, in the form yyddd, where yy is the year and ddd is 
the Julian date (001, for January 1, through 365, for December 31), 
through which the nonVSAM data set is to be kept before it is allowed 
to be deleted. 



Catalog (NonVSAM) 



CATALOG( catnameW password ] ) 

identifies the catalog in which the nonVSAM data set is to be defined. 

See "Order of Catalog Search: DEFINE" for information about the order 
in which a catalog is selected when the catalog's name is not specified. 

catname 

specifies the name of the catalog in which the entry is to be defined. 

password 

specifies the catalog's password. If the catalog is password protected, 
you must supply the update- or higher-level password. 

Abbreviation: CAT 
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DEFINE NONVSAM Example 

Define a NonVSAM Data Set: Example 1 



In this example, two existing nonVSAM data sets are defined in a VSAM 
catalog, D27UCAT1. The DEFINE NONVSAM command cannot be used to 
create a nonVSAM data set because the command does not allocate space. 

//DEFNVS JOB 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

DEFINE NONVSAM - 

(NAME (EXAMPLE. NONVSAM) - 
DEVICETYPES( 2314) - 
VOLUMES( VSER02 ) ) - 
CATALOG ( D27UCAT1/MRPWD27 ) 

DEFINE NONVSAM - 

( NAME( EXAMPLE . N0NVSAM2 ) - 
DEVICETYPES( 2314) - 
VOLUMES( VSER02 ) ) - 
CATALOG ( D27UCAT1/MRPWD27 ) 
/* 

The job control language statement is: 

« SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

Both DEFINE NONVSAM commands define a nonVSAM data set in catalog 
D27UCAT1. The DEFINE NONVSAM commands' parameters are: 

• NAME, which specifies the name of the nonVSAM data sets, 
EXAMPLE.NONVSAM and EXAMPLE.NONVSAM2. 

• DEVICETYPES, which specifies the type of device that contains the 
nonVSAM data sets, 2314 Direct Access Storage Device. 

• VOLUMES, which specify the volume that contains the nonVSAM data 
sets, VSER02. 

• CATALOG, which identifies the catalog that is to contain the nonVSAM 
entries, D27UCAT1, and its update- (or higher-level) password, 
MRPWD27. 
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DEFINE PAGESPACE 



The format of the DEFINE command when it is used to define a page space 
is: 



DEFINE 



PAGESPACE 

(N AME( entryname ) 
{CYLINDERS(/?nma/j) | 

RECORDSC/Jrimary) I 

TRACKS(/?nmarF)} 
VOLUME(vo/ser) 
[ATTEMPTSCnwrnter |2)] 
[AUTHORIZATION( entrypoint [ b string ])] 
[COUEicode)] 
[CONTROLVy^ {password )] 
[FILE(c?«a/ne)] 
[MASTERPW(/?a55worJ )] 
[MODEL( entryname [ / password ] 

[ b catname {/password ]])] 
{OWSER.{ownerid)\ 
[READPW(pfl55wor J )] 
[SWAP I NOSWAP ] 
{10{date)\¥01k{days)] 
[ UNIQUE I SUBALLOCATION] 
{VVSykTEVy^ {password )]) 

[CATALOG( catname {/ passwordYli\ 



DEFINE PAGESPACE Parameters: Summary 



The parameters of the DEFINE PAGESPACE can be divided into required 
and optional parameters. 

The required parameters are: 

• Entry type, which specifies that a page space and its catalog entry are to be 
created (PAGESPACE). 

• Name, which names the page space (NAME). 

• Allocation, which specifies the amount of space to be allocated to the page 
space and identifies its volume (VOLUMES and one of: CYLINDERS, 
RECORDS, or TRACKS). You need not explicitly specify the allocation 
parameters if you specify the MODEL parameter. 

The optional parameters are: 

• Those that apply only to the page-space data sets (SWAP and NOSWAP). 

• Allocation, which specifies 

- Whether the page space's data space is to be shared with other VSAM 
objects (SUBALLOCATION and UNIQUE). 
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• Protection and integrity, which 

- Associate passwords with the page space (MASTERPW, 
CONTROLPW, UPDATEPW, READPW). 

- Provide a mechanism by which the console operator can be prompted to 
supply a password without disclosing the name of the entry (CODE), 

- Identify a user-written routine for additional authorization verification 
(AUTHORIZATION). 

- Identify the owner of the page space (OWNER). 

- Specify a retention period for the page space (TO and FOR). 

• Model, which identifies an existing page-space entry from which attributes 
are to be copied (MODEL). 

• Catalog, which provides the name and password of the catalog in which the 
page space is to be defined (CATALOG). 

DEFINE can be abbreviated: DEF. 



DEFINE PAGESFACE Parameters 
Required Parameters 



PAGESPACE 

specifies that a page space is to be defined. 

Abbreviation: PGSPC 

NAME( entryname ) 

specifies the name of the entry being defined. 

The name may contain from 1 through 44 alphameric characters (A 
through Z, and through 9), national characters (@, #, and $), and two 
special characters (the hyphen and the 12-0 overpunch). Names containing 
more than eight characters must be segmented by periods; one to eight 
characters may be specified between periods. The first character of any 
name or name segment must be either an alphabetic or national character. 
If you specify the name in the format entryname(modifier), only that 
portion of the name preceding the left parenthesis will be used. The 
modifier enclosed in parentheses will be ignored. 

CYLINDERS( /?nma/7 ) | 

RECORDS( primary ) | 

TRACKS( primary ) 

specifies the amount of space that is to be allocated by tracks, cylinders, or 
number of records. If RECORDS or TRACKS is specified, the quantity 
specified is rounded up to the nearest cylinder and the space is allocated in 
cylinders. 

If you do not specify the MODEL parameter, you must specify one, and 
only one, of the following parameters: CYLINDERS, RECORDS, or 
TRACKS. 

To determine the exact amount of space allocated, list the page space's 
catalog entry, using the LISTCAT command. 
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. When you specify UNIQUE, and the page space's data space is the first 
data space on the volume that belongs to a recoverable catalog, an 
additional amount of (the equivalent, in tracks, of) one cylinder is allocated 
for the recovery area data space. 

primary 

specifies the amount of space that is to be allocated to the page space. 
Once the primary extent is full, the page space is full. The page space 
cannot extend onto secondary extents. 

primary can be expressed in decimal (n), hexadecimal (X'n'), or binary 
(B'n') form. 

The Auxiliary Storage Manager (ASM) uses a halfword field to contain 
a relative paging slot (record) number within a given page space (data 
set). As such, the theoretical maximum number of paging slots for each 
page space is 65,535. This limitation currently affects only page space 
allocations on a 3350 device. The maximum usable page space on a 
3350 is 504 cylinders, which is 15,120 tracks, or 65,520 slots. 

Abbreviations: CYL, REC, and TRK 

VOLUMES( volser ) 

specifies the volume that contains the page space. 

In a system with the Mass Storage System, a page space cannot reside on a 
mass storage volume. Also, a page space with the SWAP attribute cannot 
be defined on a 2314 direct access drive. 

volser 

the volume serial number, can contain one to six alphameric characters 
(A through Z, and through 9), national characters (@, #, and $), and 
special characters. When the volume serial number contains a special 
character (that is, a comma [,], semicolon [;], blank [b], period [.], 
single quote ['], ampersand [ & ], plus sign [+], equal sign [=], hyphen 
[-], parenthesis [( or )], slash [/], or asterisk [*]), enclose the volume 
serial number in single-quotation marks (for example, VOLUME 
C*DORIS*')). 

When the volume serial number contains a special character and also 
contains a single-quotation mark, code the imbedded quotation mark as 
two single-quotation marks (for example, VOLUME C*CA"ROL '.) 

You can code VOLUME in hexadecimal form. Enclose it in 
single-quotation marks and precede it with X (for example, VOLUME 
(X'E2E4C5') is the same as VOLUME (SUE).) 

You must specify the VOLUMES parameter unless you specify the 
MODEL parameter. The VOLUME parameter interacts with other 
DEFINE PAGESPACE parameters. You should take care to ensure that 
the volume(s) you specify for the page space can satisfy the page space's 
other attributes: 

• SUBALLOCATION: If suballocation is specified, the volume must 
contain a VSAM data space. 

. CYLINDERS, RECORDS, TRACKS: The volume must contain 
enough unallocated space to satisfy the page space's space requirement. 
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Optional Parameters 



• FILE: The volume information supplied with the DD statement pointed 
to by FILE must be consistent with the information specified for the 
page space. 

• CATALOG: If the page space is suballocated, the data space on the 
volume must have been defined in the same catalog that the page space 
is being defined in, and must be owned by the catalog. 

Abbreviation: VOL 



ATTEMPTS( number \ 2 ) 

specifies the maximum number of times the operator or TSO terminal user 
can try to enter a correct password in response to a prompting message. 
The number can be any number, through 7. When you define a page 
space, you should specify ATTEMPTS(O), so that the operator is not 
prompted and is not allowed to enter a password from the console. 

number 

can be expressed in decimal (n), hexadecimal (X'n'), or binary (B'n') 
form. This parameter can be coded, but only has effect when the entry's 
master password is not null. A prompting message is issued only when 
the user has not already supplied the appropriate password. 

Note to TSO users: At a TSO terminal, the logon password is checked 
first before the user is prompted to supply a password for the page 
space. Checking the logon password counts as one attempt to obtain a 
password. If ATTEMPTS is not specified, the user has one attempt to 
supply the page-space's password because the default is 2. 

Abbreviation: ATT 

AUTHORIZATION( entrypoint [ b string ] ) 

specifies that a user-security-verification routine (USVR) is available for 
additional security verification. When a protected page space is accessed 
and the user supplies a correct password other than the page-space's 
master password, the USVR receives control. 

See OS/VS Virtual Storage Access Method (VS AM), Programmer's Guide 
for details on the USVR. 

If a USVR is loaded from an unauthorized library during Access Method 
Services processing, an abnormal termination will occur. See the section 
"Authorized Program Facility" in the chapter "Introduction." 

This parameter can be coded, but only has effect when the entry's master 
password is not null. 

entrypoint 

specifies the name of the user's-security- verification routine. 

The name can contain one to eight alphameric characters (A through Z, 
and through 9), national characters ((a), #, and $), or special 
characters (the hyphen and 12-0 overpunch). The first character must 
be an alphabetic or national character. 



272 0S/VS2 Access Method Services 



DEFINE PAGESPACE 

string 
I specifies information to be passed to the user-security-verification 

routine when it receives control to verify authorization, and can contain 
1 to 255 EBCDIC characters. When the string contains a special 
character (that is, a comma [,], semicolon [;], blank [b], period [.], 
single quote ['], ampersand [ & ], plus sign [+], equal sign [=], hyphen 
[-], parenthesis [( or )], slash [/], or asterisk [*]), enclose the string in 
single-quotation marks (for example, AUTHORIZATION ( entrypoint, 
'*DORIS*')). 

When the string contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, AUTHORIZATION ( entrypoint, 
'*CA"ROL*')). 

You can code string in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
AUTHORIZATION ( entrypoint, X'E2E4C5') is the same as 
AUTHORIZATION ( entrypoint, SUE). The string can contain up to 
255 hexadecimal characters when expressed in this form, resulting in up 
to 128 bytes of information. 

Abbreviation: AUTH 

CODE( code) 

specifies a code name for the page space. If an attempt is made to access a 
password-protected entry without a password, the code name is used in a 
prompting message; the code enables the operator or TSO terminal user to 
1^^ be prompted for the password without disclosing the name of the entry. If 

code is not specified and an attempt is made to access a page space entry 
that is password protected without supplying a password, the operator or 
TSO terminal user is prompted with the name of the entry. 

This parameter can be coded, but only has effect when the cluster's or 
component's master password is not null. A prompting message is issued 
only when the user has not already supplied the appropriate password. 

code 

can contain 1 to 8 EBCDIC characters. When the code contains a 
special character (that is, a comma [,], semicolon [;], blank [b], period 
[.], single quote ['], ampersand [ & ], plus sign [+], equal sign [=], 
hyphen [-], parenthesis [( or )], slash [/], or asterisk [*]), enclose the 
code in single-quotation marks (for example, CODEC*DORIS*')). 

When the code contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, CODE('*CA"ROL*')). 

You can code code in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
CODE(X'E2E4C5') is the same as CODE(SUE). 

CONTROLPW( password ) 

specifies a control-level password for the page space. Because the page 
space is a system data set, it cannot be opened or used by a user's program. 

If a read or update password is the only password specified for the page 
\ space, it (the highest-level password) propagates upward and becomes the 

^ password for all higher unspecified levels. 
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The passwords are cataloged in both the page-space entry and its 
data-component's entry. You should specify control-, update-, and 
read-level passwords to prevent the page space from being accessed if its 
volume is moved to a VSl system. A VS2 system automatically prevents 
users from accessing page spaces and their data components. 

password 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, CONTROLPW('*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, CONTROLPWC*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
CONTROLPW(X'E2E4C5') is the same as CONTROLPW(SUE). 

Abbreviation: CTLPW 

FILE( dname ) 

specifies the name of the DD statement that identifies the device and 
volume to be allocated to the page space. If the page space is unique, and if 
the FILE parameter is not specified and the volume is physically mounted, 
the volume identified with the VOLUME parameter is dynamically 
allocated. The volume must be mounted as permanently resident or 
reserved. 

MASTERPW( password ) 

specifies a master password for the page space. The master password 
allows all Access Method Services operations against the page space entry. 
The AUTHORIZATION, CODE, and ATTEMPTS parameters have no 
effect unless the entry has a master password associated with it. If 
MASTERPW is not specified, the highest level password specified becomes 
the password for all higher levels. Because the page space is a system data 
set, it cannot be opened or used by a user's program. 

The passwords are cataloged in both the page-space entry and its 
data-component's entry. You should specify control-, update-, and 
read-level passwords to prevent the page space from being accessed if its 
volume is moved to a VSl system. A VS2 system automatically prevents 
users from accessing page spaces and their data components. 

password 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, MASTERPWC*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, MASTERPWC*CA"ROL*')). 
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1^ You can code password in hexadecimal form, where two hexadecimal 

I characters represent one EBCDIC character. For example, 

MASTERPW(X'E2E4C5') is the same as MASTERPW(SU^). 

Abbreviation: MRPW 

MODEL( entryname [ / password ] 

[ b catname [ / password ]] ) 

specifies that an existing page space entry is to be used as a model for the 
entry being defined. It is possible to use an already defined page space as a 
model for another page space. When one entry is used as a model for 
another, its attributes are copied as the new entry is defined. 

For more details on how a model is used, see "How to Use One Object as 
a Model For Another Object." 

You may use some attributes of the model and override others by explicitly 
specifying them in the definition of the page space. If you do not want to 
add or change any attributes, you need specify only the entry-type (page 
space) of the model to be used and the name of the entry to be defined. 

entryname 

specifies the name of the page space entry to be used as a model. 

password 

specifies a password. If the entry to be used as a model is password 
protected and is cataloged in a password-protected catalog, a password 
is required. If the protection attributes are to be copied, substitute the 
master password of either the entry being used as a model (following 
\ entryname) or the catalog in which the entry being used as a model is 

defined (following catname). If you specify both passwords, the 
catalog's password is used. If protection attributes are not to be copied,, 
any password can be used. 

catname 

specifies the name of the catalog in which the entry to be used as a 
model is defined. You identify the catalog that contains the model entry 
for either of these cases: 

• You specify the catalog's password instead of the model entry's 
password. i 

• The model entry's catalog is not identified with a JOBCAT or 
STEPCAT DD statement, and is not the master catalog. 

OWNER( ownerid ) 

specifies the identification of the owner of the page space. 

ownerid 

can contain 1 to 8 EBCDIC characters. 

When the ownerid contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the ownerid in single-quotation marks (for 
example, OWNERC*DORIS*')). 

When the ownerid contains a special character and also contains a 
\ single-quotation mark, code the imbedded quotation mark as two 

^ single-quotation marks (for example, OWNERC*CA"ROL*')). 
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You can code ownerid in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
OWNER(X'E2E4C5') is the same as OWNER(SUE). 

Note to TSO users: If the owner is not identified with the OWNER 
parameter, the TSO user's userid becomes the ownerid. 

READPW( ;7as5w<?rJ) 

specifies a read level password for the page space. Because the page space 
is a system data set, it cannot be opened or used by a user's program. 

The passwords are cataloged in both the page space entry and its data 
component's entry. You should specify control-, update-, and read-level 
passwords to prevent the page space from being accessed if its volume is 
moved to a VSl system. A VS2 system automatically prevents users from 
accessing page spaces and their data components. 

password -' 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, READPWC*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, READPWC*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
READPW(X'E2E4C5') is the same as READPW(SUE). 

Abbreviation: RDPW 

SWAP I NOSWAP 

specifies for which group of pages the page space will be used. Auxiliary 
Storage Management separates private-area address space pages into two 
distinct groups: Local System Queue Area (LSQA) pages and pageable 
private-area pages. SWAP specifies that the page space is a high-speed 
data set used during a swap operation to store and retrieve the set of 
LSQA pages owned by an address space. NOSWAP indicates that the page 
space is a conventional page space used to record pageable private area 
pages. 

A page space with the SWAP attribute cannot be defined on a 2314 direct 
access device. 

Abbreviation: NSW AP 

TO( date ) | FOR( days ) 

specifies the retention period for the page space. 

If neither TO nor FOR is specified, the page space can be deleted at any 
time. 

TO( date ) 

specifies the date, in the form yyddd, where yy is the year and ddd is the 
number (001 through 365) of the day, through which the cluster being 
defined is to be kept. 
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FOR( days ) 

specifies the number of days for which the page space is to be kept. The 
maximum number that can be specified is 9999. If the number specified 
is through 1830, the page space is retained for the number of days 
specified; if the number is between 1831 and 9999, the page space is 
retained through the year 1999. 

days 

can be expressed in decimal (n), hexadecimal (X'n'), or binary (B'n') 
form. 

UNIQUE I SUBALLOCATION 

specifies whether the page space is allocated an amount of space from the 
volume's available space (UNIQUE) or from a previously defined VSAM 
data space (SUBALLOCATION). When UNIQUE is specified, the page 
space is allocated a VSAM data space of its own. VSAM generates a name 
for the data space and builds a format- 1 DSCB in the volume's VTOC to 
describe it. If SUBALLOCATION is specified, the name of the data space, 
not of the page space, appears in the VTOC. A data space must have been 
defined on the volume on which the page space is defined. 

Auxiliary Storage Management recommends that UNIQUE be used for 
page space data sets. This will cause VSAM to allocate a single nonshared 
data space for the page data set. Space from another data space will not be 
used, eliminating one of the possibilities for multiple extent data sets which 
will cause Auxiliary Storage Management performance degradation. 

Abbreviations: UNQ and SUBAL 

UPDATEPW( password ) 

specifies an update-level password for the page space. Because the page 
space is a system data set, it cannot be opened or used by a user's program. 

If a read password is the only password specified for the page space (that 
is, it is the highest-level password), it propagates upward and becomes the 
password for all higher levels. If you specify a higher-level password and 
do not specify an update password, the update password is nuU. 

The passwords are cataloged in both the page space entry and its data 
component's entry. You should specify control-, update-, and read-level 
passwords to prevent the page space from being accessed if its volume is 
moved to a VSl system. A VS2 system automatically prevents users from 
accessing page spaces and their data components. 

password 

is a one-to-eight EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [==], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, UPDATEPWC*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, UPDATEPW('*CA"ROL*')). 
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You can code password in hexadecimal form, wliere two hexadecimal 
characters represent one EBCDIC character. For example, 
UPDATEPW(X'E2E4C5') is the same as IJPDATEPW(SUE). 



Abbreviation: UPDPW 
Catalog (Page Space) 



CATALOG( catname [ / password ] ) 

specifies the name and password of the catalog in which the page space is 
to be defined. 

When the CATALOG parameter identifies a user catalog, you must also 
supply a STEPCAT or JOBCAT DD statement to describe and allocate the 
user catalog. See "Order of Catalog Use: DEFINE" for information about 
the order in which catalogs are used. 

catname 

specifies the name of the catalog. 

password 

specifies a password. If the catalog is password protected, you must 
supply the catalog's update- or higher-level password. If no password is 
specified, VSAM asks the operator or TSO terminal user for the correct 
password. 

Abbreviation: CAT 
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DEFINE PAGESPACE Examples 

Define a Conventional (NOSWAP) Page Space: Example 1 

In this example, a page space is defined. 

//DEFPGSP1 JOB 

//STEP1 EXEC PGM=IDCAMS 

//VOLUME DD VOL=SER=VSER05,UNIT=2305,DISP=OLD 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

DEFINE PAGESPACE - 

( NAME ( SYS 1 .PAGE2 ) - 

CYLINDERS ( 10) - 

VOLUMES (VSERO 5) - 

CONTROLPW(PASSWD1 ) - 

UPDATEPW( PASSWD2 ) - 

READPW( PASSWD3 ) ) 
/* 

The job control language statements are: 

• VOLUME DD, which describes the volume on which the data space is to 
be defined. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

Because no catalog is explicitly specified with a CATALOG parameter or 
with JOBCAT or STEPCAT DD statements, VSAM assumes that the data 
space and page space are to be defined in the master catalog. 

The DEFINE PAGESPACE command defines a page space. This page space 
will have the UNIQUE attribute and hence a new data space will be created 
for its exclusive use. Its parameters are: 

• NAME, which specifies the name of the page space, SYS LP AGE2. 

• CYLINDERS, which specifies that the page space is to occupy ten 
cylinders. The page spaces are never extended. 

• VOLUMES, which specifies that the page space is to reside on volume 
VSER05. 

• CONTROLPW, which specifies the control password for the page space is 
PASSWDL 

, • UPDATEPW, which specifies the update password for the page space is 
PASSWD2. 

• READPW, which specifies the read password for the page space is 
PASSWD3. 

Because neither UNIQUE nor SUBALLOCATION has been specified, the 
page space defaults to UNIQUE. Because neither SWAP nor NOSWAP has 
been specified, the page space defaults to NOSWAP. 



K 
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Define a SWAP Page Space: Example 2 



In this example, a unique page space is defined. A unique page space differs 
from a suballocated page space in that a unique page space occupies an entire 
VSAM data space. When a unique page space is defined, a VSAM data space 
is automatically buUt for the page space. When space is allocated to a unique 
page space, the volume's VTOC identifies the space with the name of the 
page space. 

//DEFPGSP2 JOB ... 
//STEPT EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYS IN DD * 

DEFINE PAGESPACE - 

(NAME(SYS1 .PAGE1 ) - 

CYLINDERS ( 10 ) - 

VOLUMES( VSER05 ) - 

SWAP - 

C0NTR0LPW(PASSWD1 ) - 

UPDATEPW( PASSWD2 ) - 

READPW( PASSWD3 ) ) 
/* 

The DEFINE PAGESPACE command defines a page space. Its parameters 
are: 

• NAME, which specifies the name for the page space: SYS 1. PAGE 1. 
Because the page space is unique, the page space's name is put into the 
DSCB (in the volume's VTOC) that describes the space allocated to the 
page space. 

• CYLINDERS, which specifies that the page space occupies 10 cylinders 
and cannot be extended. 

• VOLUMES, which identifies the volume on which the page space is to 
reside. Because no DD statement describes the volume, the volume is 
dynamically allocated. Volume VSER05 must be mounted as permanently 
resident or reserved. 

. SWAP, which specifies the page space will be used to store Local System 
Queue Area (LSQA) pages. 

• CONTROLPW, which specifies the control password for the page space is 
PASSWDl. 

• UPDATEPW, which specifies the update password for the page space is 
PASSWD2. 

• READPW, which specifies the read password for the page space is 
PASSWD3. 

Because neither UNIQUE nor SUBALLOCATION has been specified, the 
page space defaults to UNIQUE. 

Because neither a CATALOG parameter nor a JOBCAT or STEPCAT DD 
statement was specified, VSAM assumes that the page space is to be defined 
in the master catalog. 
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DEFINE PATH 



The format of the DEFINE command when it is used to define a path is: 



DEFINE 



PATH 

(N AME( entryname ) 
VXTUEKTRYi^entryname {/password ]) 
[ATTEMPTS(nMml>er |2)] 
[AUTHORIZATION(enro7'omf [b string ])] 
[CODEC corfe)] 
[CONTROLPW(pa$5worcf )] 
[FILE( f/name)] 
[MASTERPWC/xwswor J )] 
[MODEL( entryname [/password ] 

[b catname [/password]])] 
[OWNERiownerid)] 
[READPWipassword}] 
[TO(date)\¥OR{days)] 
[ UPDATE I NOUPDATE] 
[UPDATEPW(/?as5wor^)] ) 
[CATALOG! catname [/password ])] 



DEFINE PATH Parameters: Summary 



The parameters of the DEFINE PATH command can be grouped as required 
and optional parameters. 

The required parameters are: 

• Entry type, which specifies that a path catalog entry is to be created 
(PATH). 

• Name, which names the path and the entry that it points to (NAME and 
PATHENTRY). 

The optional parameters are: 

• Allocation, which identifies the catalog recovery volume that contains the 
alternate index or cluster that the path points to (FILE). This parameter is 
required when the path is defined in a recoverable catalog. 

• Protection and integrity, which 

- identify the path to a console operator without revealing the path's entry 
name (CODE and ATTEMPTS). 

- identify a user-written-security verification routine for additional 
authorization verification (AUTHORIZATION). 

- specify a retention period for the path (FOR or TO). 

- associate passwords with the path (MASTERPW, CONTOLPW, 
UPDATEPW, and READPW). 

- identify the owner of the path (OWNER). 

• Model, which identifies an existing path entry that is to be used as a model 
for the path being defined (MODEL). 
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• Update, which specifies whether the cluster's upgrade set is to be opened 
when the path (and its cluster) is opened (UPDATE or NOUPDATE). 

• Catalog, which identifies the catalog that contains the alternate index or 
cluster entry that the path entry is to point to (CATALOG). 

DEFINE may be abbreviated: DEF. 



DEFINE PATH Parameters 

Required Parameters 



Optional Parameters 



PATH 

specifies that a path is to be defined. 

The PATH keyword is followed by parameters which name the path and 
its related object, and which specify the path's attributes. 

NAME( entryname ) 

specifies the path's name. 

entryname 

can contain 1 to 44 alphameric characters (A through Z, and through 
9), national characters (@, #, and $), and special characters (the 
hyphen (-), and the 12-0 overpunch (X'CO')). 

When the name contains more than eight characters, you divide the 
name into segments of 1 to 8 characters each and separate the segments 
with (.) periods. The name's first character (and each segment's first 
character) is either an alphabetic character or a national character. If 
you specify the path's name in the format entryname(modifier), only that 
portion of the path's name preceding the left parenthesis will be used. 
The modifier enclosed in parentheses will be ignored. 

PATHENTRY( entryname [ / password] ) 

when the path consists of an alternate index and its base clusters, 
entryname identifies the alternate-index entry. When the path is opened to 
process data records, both the alternate index and the base cluster are 
opened. 

When the path consists of a cluster without an alternate index, entryname 
identifies the cluster. You can define the path as though it were an alias for 
the cluster. This allows you to specify no-update access to the cluster, so 
that the upgrade set wiU not be required or updated when the cluster is 
opened. You can also establish protection attributes for the alternate name, 
separate from the protection attributes of the cluster. 

If the cluster or alternate-index entry is password protected, you must 
supply the entry's master password. When you identify the catalog with the 
CATALOG parameter, you can supply the catalog's master password 
instead of the entry's password. 

Abbreviation: PENT 



ATTEMPTS( number j 2 ) 

specifies the maximum number of times the operator can try to enter a 
correct password in response to a prompting message. 

This parameter can be coded, but only has effect when the path's master 
password is not null. A prompting message is issued only when the user has 
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not already supplied the appropriate password. 

number 

is an integer from to 7 and can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n') form. 

Note to TSO users: At a TSO terminal, the logon password is checked first 
before the user is prompted to supply a password for the path. Checking 
the logon password counts as one attempt to obtain a password. If 
ATTEMPTS is not specified, the user has one attempt to supply the path's 
password because the default is 2. 

Abbreviation: ATT 

AUTHORIZATION( entrypoint [b string\) 

specifies that a user-security-verification routine (USVR) is available for 
additional security verification. When a protected path is accessed and the 
user supplies a correct password other than the cluster's master password, 
the USVR receives control. See OS/VS Virtual Storage Access Method 
(VSAM) Programmer's Guide for details on the USVR. 

If a USVR is loaded from an unauthorized library during Access Method 
Services processing, an abnormal termination will occur. See the section 
"Authorized Program Facility" in the chapter "Introduction." 

This parameter can always be coded, but only has effect when the path's 
master password is not null. 

entrypoint 

specifies the name of the USVR. entrypoint can contain 1 to 8 
alphameric characters (A through Z, and through 9), national 
characters (@, #, and $), and special characters (the hyphen(-) and the 
12-0 overpunch (X'CO')). The name's first character is either an 
alphabetic character or a national character. 

string 

specifies information to be passed to the USVR when it receives control 
to verify authorization, string can contain 1 to 255 EBCDIC characters. 

When the string contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the string in single-quotation marks (for 
example, AUTHORIZATION( entrypoint, '*DORIS*')). 

When the string contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, AUTHORIZATION ( entrypoint, 
'*CA"ROL*')). 

You can code string in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
AUTHORIZATION( entrypoint, X'E2E4C5') is the same as 
AUTHORIZATION( entrypoint, SUE). The string can contain up to 
255 hexadecimal characters when expressed in this form, resulting in up 
to 128 bytes of information. 

Abbreviation: AUTH 



Command Format 283 



CODEC code ) 

specifies a code name for the path. If an attempt is made to access a 
password-protected path without first suppljdng an appropriate password, a 
prompting message is issued to the operator's console. The prompting 
message includes the code name, which identifies the path without 
revealing its entry name. 

This parameter can be coded, but only has effect when the path's master 
password is not null. A prompting message is issued only when the user 
hasn't already supplied the appropriate password. When CODE is not 
specified, the prompting message identifies the path with its entry name. 

code 

can contain 1 to 8 EBCDIC characters. 

When the code contains a special character (that is, a comma [J, 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the code in single-quotation marks (for 
example, CODE('*DORIS*')). 

When the code contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, CODEC*CA"ROL*')). 

You can code code in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
CODE(X'E2E4C5') is the same as CODE(SUE). 

CONTROLPW( password ) 

specifies a control password for the path. Control interval processing is not 
permitted through a path; the control password wiU permit read and write 
operations against the base cluster. 

If a read or update password is the only password specified for the object, 
it (the highest-level password) propagates upward and becomes the 
password for all higher unspecified levels. 

password 

is a 1 - to 8-EBCDIC-character password. 

When the password contains a special character (that is, a cQmma [,], 
semicolon [;1, blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, CONTROLPWC*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, CONTROLPWC*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
CONTROLPW(X'E2E4C5') is the same as CONTROLPW(SUE). 

Abbreviation: CTLPW 
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FILE( dname ) 

specifies the name of a DD statement that identifies the recovery volume 
of the alternate index or cluster named with the PATHENTRY parameter. 
FILE is only required when the path is defined in a recoverable catalog. 

The recovery volume is the first volume of the base cluster's index 
component when PATHENTRY names a key-sequenced cluster or an 
alternate index over a key-sequenced cluster. 

The recovery volume is the first volume of the base cluster's data 
component when PATHENTRY names an entry-sequenced cluster or 
an alternate index over an entry-sequenced cluster. 

When FILE is not specified, the cluster's recovery volume is dynamically 
allocated. The volume must be mounted as permanently resident or 
reserved. 

MASTERPW( password ) 

specifies a master password for the path. The master password allows all 
operations against the path. 

If the master password is not specified, the path's highest-level password 
propagates upward and becomes the password for all higher levels, 
including the master password. 

If aU passwords are null, ATTEMPTS, AUTHORIZATION, and CODE 
can be coded but have no effect until the master password is specified. 

password 

is a 1- to 8-EBCDIC-character password. 

When the password contains a special character (that is, a comma [,], 
semicolon. [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, MASTERPW('*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, MASTERPW('*CA"ROL*')). 

You caii code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
MASTERPW(X'E2E4C5') is the same as MASTERPW(SUE). 

Abbreviation: MRPW 

MODEL ( entryname [ / password ] 

[ b catname [ / password ]] ) 

identifies an existing path entry that is to be used as a model for the path 
being defined. For details about how a model is used, see "How to Use 
One Object as a Model for Another Object." 

You can use some attributes of the model and override others by explicitly 
specifying them in the definition of the path. When you do not want to add 
or change any attributes, you specify only the entry-tjrpe (PATH), the 
path's name, its alternate-index's (or cluster's) name, and the 
model-entry's name. 
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entryname 

names the entry to be used as a model, entryname must name a path 
entry. 

password 

specifies a password. If the model entry is password protected and it is 
cataloged in a password-protected catalog, you must supply the read (or 
higher level) password of either the model entry or its catalog. If you 
specify both passwords, the catalog's password is used. 

If you are not specifying new protection attributes for the path (that is, 
the model's passwords and protection attributes are being copied), you 
must supply the master password of either the model entry or its 
catalog. 

catname 

names the model-entry's catalog. You must identify the catalog that 
contains the model entry for either of these cases: 

• You specify the catalog's password instead of the model-entry's 
password 

• The model-entry's catalog is not identified with a JOBCAT or 
STEPCAT DD statement, and is not the master catalog. 

If the catalog's volume is physically mounted, it is dynamically allocated. 
The volume must be mounted as permanently resident or reserved. See 
"Order of Catalog Use: DEFINE" for information about the order in 
which a catalog is selected when the catalog's name is not specified. 

OWNER( ownerid ) 

specifies the identification of the path's owner. 

ownerid 

can contain 1 to 8 EBCDIC characters. 

When the ownerid contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the ownerid in single-quotation marks (for 
example, OWNERC*DORIS*')). 

When the ownerid contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, OWNER('*CA"ROL*')). 

You can code ownerid in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
OWNER(X'E2E4C5') is the same as OWNER(SUE). 

Note to TSO users: If the owner is not identified with the OWNER 
parameter, the TSO user's userid becomes the ownerid. 

READPW( password ) 

specifies a read password for the path. The read password permits read 
operations against the base cluster's data records. 

password 

is a 1- to8-EBCDIC-character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
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or asterisk [*]), enclose the password in single-quotation marks (for 
example, READPWC*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, READPWC*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
READPW(X*E2E4C5') is the same as READPW(SUE). 

Abbreviation: RDPW 

TO( date )\FORidays ) 

specifies the retention period for the path. The path is not automatically 
deleted when the expiration date is reached. When a retention period is not 
specified, the path can be deleted at any time. 

TO( date ) 

specifies the date, in the form yyddd, where yy is the year and ddd is 
the Julian date (001, for January 1, through 365, for December 31), 
through which the path is to be kept before it is allowed to be deleted. 

FOR( days ) 

specifies the number of days for which the entry is to be kept before it is 
allowed to be deleted, days can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n') form. The maximum number that 
can be specified for days is 9999. If the number specified is through 
1830, the retention period is the number of days specified. If the 
number specified is between 1831 and 9999, the retention period is 
through the year 1999. 

UPDATE I NOUPDATE 

specifies whether the base-cluster's upgrade set is to be allocated when the 
path is opened for processing. 

The upgrade set is a group of alternate indexes associated with the base 
cluster. The alternate indexes are opened whenever the base cluster is 
opened. When records in the base cluster are modified or deleted, and 
when records are added to the base cluster, each alternate index in the 
base-cluster's upgrade set is modified to reflect the change in the cluster's 
data, just as a key-sequenced cluster's index is modified each time the 
cluster's data changes. 

When a path points to a base cluster that has a large upgrade set (that is, 
many alternate indexes are associated with the base cluster), and the path 
is defined with the NOUPDATE attribute, you can open the path, and 
consequently the base cluster, and none of the alternate indexes will be 
opened. 

NOUPDATE specifies that, when opening the path, the path's base cluster 
is to be allocated and the base cluster*s upgrade set is not to be allocated. 
You can specify the NOUPDATE attribute for the path even though the 
UPGRADE attribute is set for one of the base-cluster's alternate indexes. 

Abbreviations: UPD and NUPD 
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UPDATEPW( password ) 

specifies the update password for tlie path. The update password permits 
read and write operations against the base cluster's data records. 

If a read password is the only password specified for the object (that is, it 
is the highest-level password), it propagates upward and becomes the 
password for all higher levels. If you specify a higher-level password and 
don't specify an update password, the update password is null. 

password 

is a 1- to 8-EBCDIC-character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, UPDATEPW('* DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, UPDATEPWC*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
UPDATEPW(X'E2E4C5') is the same as UPDATEPW(SUE). 

Abbreviation: UPDPW 



The catalog parameter allows you to supply the name and password of the 
catalog in which the path is to be defined. 

CATALOG( catname [/ password ] ) 

identifies the catalog that contains the entry of the cluster or alternate 
index named in the PATHENTRY parameter. 

See "Order of Catalog Use: DEFINE" for information about the order in 
which a catalog is selected if the catalog's name is not specified. 

If the cluster's or alternate-index's entry is password protected and its 
catalog is also password protected, you must specify the master password 
for either the entry or the catalog. 

catname 

specifies the catalog's name. 

password 

specifies the catalog's master password. 

If the catalog's volume is physically mounted, it is dynamically allocated. 
The volume must be mounted as permanently resident or reserved. 

Abbreviation: CAT 
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Define a Path: Example 1 



DEFINE PATH 



In this example, a path is defined. Previous examples illustrated the definition 
of the path's alternate index, EXAMPLE.AIX, and the alternate index's base 
cluster, EXAMPLE.KSDS2. The alternate index, path, and base cluster are 
defined in the same catalog, AMASTCAT. 



//DEFPATH 


JOB 


. . . 




//STEP1 


EXEC 


PGM= 


= IDCAMS 


//SYSPRINT 


DD 


SYSOUT=A 


//SYSIN 


DD 


* 




DEFINE PATH 


- 





/' 



( NAME ( EXAMPLE . PATH ) - 
PATHENTRY( EXAMPLE . AIX/AIXMRPW ) - 
READPW( PATHRDPW ) ) - 
CATALOG! AMASTCAT/MCATUPPW ) 



The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DEFINE PATH command builds a path entry to define the path 
EXAMPLE.PATH. A copy of the path entry is placed in the catalog recovery 
area, since the path entry is being defined into a recoverable catalog. The 
catalog recovery area on volume VSER04 is dynamically allocated. The 
command's parameters are: 

. NAME, which specifies that the path's name is EXAMPLE.PATH. 

• PATHENTRY, which identifies the alternate index, EXAMPLE.AIX, that 
the path provides access to. 

• READPW, which specifies the path's read password, PATHRDPW. 

• CATALOG, which in this example supplies the master catalog's update 
password, MCATUPPW. 
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DEHNE SPACE 



The format of the DEFINE command when it is used to define a data space 
is: 



DEFINE 



SPACE 

({CANDIDATE | 

CYUNDERSiprimary [ h secondary ]) | 
RECORDSC/^nma/y [ t> secondary ]) 

hRECORDSlZEiaverage h maximum ) 
TKACKSiprimary [ h secondary ])} 
VOLUMES! vo/5er[b volser...]) 
[FlLEidname)] ) 

[CATALOGC catname [/password ])] 



The parameters of the DEFINE SPACE command can be divided into 
required and optional parameters. 

The required parameters are: 

• Allocation, which specifies the amount and type of space to be allocated to 
the data space, and the volume that is to contain the data space 
(VOLUMES, CYLINDERS, RECORDS, TRACKS, RECORDSIZE, and 
CANDIDATE). 

The optional parameters are: 

• Allocation, which: 

- Specifies the DD statement which identifies and allocates the volume 
where the space is to be allocated (FILE). 

• Catalog, which identifies the catalog in which the data space is to be 
defined (CATALOG). 

DEFINE may be abbreviated: DEF. 



DEFINE SPACE Parameters 



Required Parameters 



SPACE 

specifies that a data space is to be defined. You can also use the DEFINE 
SPACE command to reserve a volume for VSAM's future use. The SPACE 
keyword is followed by the allocation parameters, enclosed in parentheses, 
that describe the space, and by the catalog parameter that identifies the 
catalog that owns the volume. 

Abbreviation: SPC 

CANDIDATE | 

CYLINDERS(pr/marv[b secondary]) \ 

RECORDS(pnmarj[b secondaryi)h RECORDSIZE {average h maximum) \ 

TRACKS (primary [b secondary]) 

specifies a volume(s) is to be reserved for VSAM's future use or specifies 
the amount of space to be allocated in terms of cyUnders, number of 
records, or tracks. 
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CANDIDATE 

specifies that the volumes listed in the VOLUMES parameter are reserved 
for future use by VSAM. An ownership indicator is set in a format-4 
DSCB in the volume's table of contents (VTOC). The volumes are 
reserved for use by the catalog, but no space is allocated (other than the 
primary CRA allocation if the catalog is recoverable). Each volume so 
reserved is called a candidate volume. If CANDIDATE is not specified, 
you must specify one of the following parameters: CYLINDERS, 
TRACKS, or RECORDS. 

If a VSAM data space already exists on the volume, you cannot specify 
CANDIDATE. (You can, however, use the ALTER command to identify 
the volume as a candidate volume for a VSAM object other than the 
volume's catalog.) 

Abbreviation: CAN 

CYhmDERSi primary [h secondary]) | 

RECORDS( primary [b secondary ] ) 

b RECORDSIZE (average b maximum ) | 

TRACKS ( primary [h secondary]) 

specifies the amount of space to be allocated in terms of tracks, cylinders, 
or number of records. If RECORDS is specified, the space required is 
calculated in terms of the number of records, but the space is allocated by 
tracks. However, if you specify TRACKS or RECORDS and if the 
minimum number of tracks should exceed a cylinder, space is allocated in 
terms of cylinders. 

primary 

specifies the initial amount of space (primary extent) to be allocated to 
the data space, primary can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n') form. 

secondary 

specifies the amount of space that is to be allocated to the data space 
each time it is extended. Once the primary extent is filled, the data space 
can expand to include a maximum of 15 secondary extents if you have 
specified a secondary-extent amount, secondary can be expressed in 
decimal (n), hexadecimal (X'n'), or binary (B'n') form. 

The secondary space allocation is rounded upward to the nearest whole 
cylinder regardless of your specification in terms of TRACKS or 
RECORDS. Consequently, the total amount of space allocated to the 
data space might exceed the predicted limit. 

When the data space is the first data space on a volume that belongs to a 
recoverable catalog, the primary amount is increased by one cylinder. 

You must specify one, and only one, of the following parameters: 
CANDIDATE, CYLINDERS, TRACKS, or RECORDS. When you 
specify RECORDS, you must also specify RECORDSIZE. When you 
specify CYLINDERS or TRACKS, you cannot specify RECORDSIZE. 

Abbreviatioiis: CYL, REC, and TRK 

RECORDSIZE( average b maximum ) 

specifies the average and maximum lengths, in bytes, of the records. 

average and maximum can be any integer value between 1 and 32,761, 
expressed in decimal (n), hexadecimal (X'n'), or binary (B'n') form. 
When you specify the RECORDS parameter, you must also specify 



292 OS/VS2 Access Method Services 



Optional Parameters 



Catalog (Space) 



DEFINE SPACE 

RECORDSIZE. Otherwise, you cannot specify RECORDSIZE. 

Abbreviation: RECSZ 

VOLUMES( vober [ b volser ... ]) 

specifies the volumes on which data spaces are to be defined. If two or 
more volumes are specified and an amount of space is specified (that is, 
TRACKS, CYLINDERS, or RECORDS and RECORDSIZE is specified) 
the amount specified for the primary allocation is allocated on each 
volume. The specified volumes must all be of the same device type. When 
the volume already has a data space on it, subsequent data spaces can be 
defined and must be cataloged in the catalog that owns the volume. A data 
space can be defined on a mass storage volume. 

A volume serial number, voher, may contain one to six alphameric, 
national ((a), #, and $), and, except under TSO, special characters. The 
special characters include commas, blanks, semicolons, parentheses, 
slashes, asterisks, periods, quotation marks, ampersands, plus signs, 
hyphens, and equal signs. A volume serial number must be enclosed in 
single quotation marks if it contains a special character. Single quotation 
marks within a volume serial number must be coded as two single 
quotation marks. 

Abbreviation: VOL 



FILE( dname ) 

specifies the name of the DD statement that identifies the device type and 
volumes to be used for space allocation. You cannot use concatenated DD 
statements to describe more than one volume. 

If FILE is not specified and the volume is physically mounted, the 
volume(s) identified with the VOLUMES parameter is dynamically 
allocated. Each dynamically allocated volume must be mounted as 
permanently resident or reserved. 



CATALOG( catname [ / password ] ) 

identifies the catalog in which the data space is to be defined. The catalog 
parameter is used to supply the name and password, when required, of the 
catalog that contains the volume entry that describes the volume on which 
the data space is to be allocated. If the DEFINE SPACE command is used 
to allocate the volume's first VSAM data space or to identify the volume as 
a candidate volume, the catalog parameter identifies the catalog that is to 
contain the volume's catalog entry and is to own the volume. (For more 
information about VSAM volume ownership, see the section. "VSAM 
Volume Ownership" in the "Introduction.") 

If the catalog's volume is physically mounted, it is dynamically allocated. 
See "Order of Catalog Use: DEFINE" for information about the order in 
which catalogs are used. 
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catname 

specifies the name of the catalog. 

password 

specifies a password. If the catalog is password protected, you must 
supply the update- or higher-level password. 

Abbreviation: CAT 



294 0S/VS2 Access Method Services 



DEFINE SPACE Example 
Define a Data Space: Example 1 



In this example, a data space is defined. The data space is to be used to 
allocate space for VSAM clusters that are subsequently defined. 

//DEFSPC1 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DEFINE SPACE - 

( CYLINDERS ( 100 10) - 
VOLUMES{VSER05) ) 
/* 

VSAM assigns a name to the data space and keeps track of it for future data 
set space allocation. Because no user catalog is specified in this example, the 
master catalog is assumed as the default. (It is the first catalog found because 
no JOBCAT or STEPCAT DD statements were specified. See the previous 
section "Order of Catalog Use: DEFINE" for more details.) 

The job control language statement is: 

• ■ SYSPRINT DD, which is required in all Access Method Services job steps. 

The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DEFINE SPACE command defines a VSAM data space. Its parameters 
are: • 

• CYLINDERS, which specifies that 100 cylinders are to be allocated for the 
data space. When the data space is extended, it is to be extended in 
increments of ten cylinders. 

• VOLUMES, which specifies the volume serial number of the volume on 
which the data space is to be defined: VSER05. 

Access Method Services defines the data space and allocates its space on 
volume VSER05. The data space is cataloged in the master catalog, because 
the DEFINE command does not include a CATALOG parameter, and 
because no JOBCAT or STEPCAT DD statements are specified. All future 
data spaces and clusters on volume VSER05 must also be cataloged in the 
master catalog. NonVSAM data sets on the volume reside in areas that are 
not allocated to a VSAM data space. 

To reserve a 3330 volume for VSAM's exclusive use, define the data space on 
it as 403 cylinders (this allows one cyUnder to be used for the volume's table 
of contents — VTOC — and the volume's label) or define other data spaces on 
the volume with additional DEFINE SPACE commands (which can be given 
in the same job step) so that all the volume's space is part of a VSAM data 
space. 
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DEFINE USERCATALOG 



DEFINE USERCATALOG 



When you define a catalog, you can specify attributes for the catalog as a 
whole and for the catalog's components. 

The format of the DEFINE command when it is used to define a catalog is: 



DEFINE 



USERCATALOG | MASTERCATALOG 

(N AME( entryname ) 

{CYLINDERS(/>nmarv [ b secondary ]) | 
RECORDSCpn'mary [ fe secondary ]) | 
TRACYtSiprimary [ b secondary ])} 

VOLUME(vo/ser) 

[ATTEMPTSC «Mm6er |2)] 

{MjmO^mKTlO^ientrypoint [h string ])] 

[BUFFERSPACE(size 1 3072 )] 

[CODEC cotie)] 

[CONTROLPW(/>asswor J )] 

[DESTAGEWAIT | NODESTAGEWAIT ] 

{YllMidname)] 

[MASTERPW(pas5wor</ )] 

[MODEL( entryname {/password ] 
[fe catname {/ password^i\Ji\ 

[OWNERCownerw/)] 

[READPWCpajswor^ )] 

[RECOVERABLE | NOTRECQVERABLE ] 

{10idate)\¥OR{days)\ 

[\}¥TykTEVV^ {password )] 

[WRTTECHECK | NOWRTTECHECK ] ) 

[DATA 

([BUFFERSPACEC size )] 
[CYLINDERSCjpn'mflrF [ b secondary ]) | 
RECORDSCpnwao' [ fe secondary ]) | 
TRACKS(/>nma/y [ b secondary ])] 
[DESTAGEWAIT | NODESTAGEWAIT] 
[RECOVERABLE | NOTRECOVERABLE] 
[WRFTECHECK I NOWRITECHECK] )] 

[INDEX 

([CYLINDERSC/Jnmflrv) I 

RECORDS(/?nmarv)l 

TRACKS(/7nmarK)] 
[DESTAGEWAIT | NODESTAGEWAIT] 
[WRTTECHECK | NOWRITECHECK] )] 

[CATALOG! mastercatname [/password ])] 
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DEFINE USERCATALOG Parameters: Summary 



The parameters of the DEFINE USERCATALOG | MASTERCATALOG 
command can be divided into required and optional parameters. 

The required parameters are: 

• Entry type, which specifies that a user catalog is to be defined 
(USERCATALOG or MASTERCATALOG). 

• Name, which names the catalog (NAME). 

• Allocation, which 

- Specifies the space to be allocated for the catalog's data space (one 
of CYLINDERS, RECORDS, or TRACKS). 

- Specifies the volume on which the catalog is to reside (VOLUME). 
The optional parameters are: 

• Allocation, which describes: 

- The name of the DD statement which describes the catalog volume 
(FILE). 

- The space for the catalog itself (one of CYLINDERS, RECORDS, or 
TRACKS). 

- The space to be used for buffers when the catalog is accessed 
(BUFFERSPACE). 

- Whether a catalog recovery area is to be defined (RECOVERABLE or 
NOTRECO VERABLE) . 

• Protection and integrity, which 

- Associate passwords with the catalog. (MASTERPW, CONTROLPW, 
UPDATEPW, READPW). 

- Provide a mechanism by which the console operator can be prompted to 
supply a password without disclosing the name of the catalog (CODE). 

- Identify a user-written routine for additional authorization verification 
(AUTHORIZATION). 

- Identify the owner of the catalog (OWNER). 

- Specify the time for which the catalog is to be kept (TO or FOR). 

- Specify whether the write-check operation is to be performed 
(WRITECHECK or NOWRITECHECK). 

- Specify whether a user catalog that is stored on a mass storage volume is 
to be destaged synchronously or asynchronously with respect to the 
program that closes it (DESTAGEWAIT or NODESTAGEWAIT). 

• Model, which identifies an existing catalog from which attributes are to be 
copied for the definition of a new user catalog (MODEL). 

e Components, which allows you to specify attributes separately for the 
catalog's data and index components (DATA and INDEX). 

• Catalog, which supplies the name and password, when required, of the 
master catalog (CATALOG). 

DEFINE can be abbreviated: DEF, 
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DEFINE USERCATALOG Parameters 



Required Parameters 



USERCATALOGC options ) 

specifies that a user catalog is to be defined. USERCATALOG is followed 
by the parameters specified for the catalog as a whole. 

(In OS/VS2 MVS, when you specify MASTERCATALOG the result is 
the same; a user catalog is created. You can, however, establish a user 
catalog as a master catalog at IPL time. See "Appendix H: Changing the 
Attributes of the VSAM Master Catalog" for a description of this 
procedure.) 

Abbreviation: UCAT 

NAME( entryname ) 

specifies the name of the catalog being defined. 

The name may contain from 1 through 44 alphameric characters (A 
through Z, and through 9), national characters (@, #, and $), and two 
special characters (the hyphen and the 12-0 overpunch). 

Names containing more than eight characters must be segmented by 
periods; one to eight characters may be specified between periods. The 
first character of any name or name segment must be either an alphabetic 
or a national character. If you specify the name in the format entryname 
(modifier), only that portion of the name preceding the left parenthesis will 
be used. The modifier enclosed in parentheses will be ignored. 

CYLINDERS( primary [b secondary^) \ 

RECORDSC primary [h secondary]) | 

TRACKS( primary [fe secondary]) 

specifies the amount of space to be allocated in terms of tracks, cylinders, 
or number of records. You can specify the amount of space as a parameter 
of USERCATALOG, as a parameter of USERCATALOG and DATA, or 
as a parameter of USERCATALOG, DATA, and INDEX. See the section 
"How Space is Assigned to a Catalog" for a description of the difference 
in space allocation depending on which combination you use. See the 
section "Estimating the Catalog's Space Requirements" for information 
about estimating the amount of space to be specified for a catalog. 

When you specify less than one cylinder of space, and the catalog is 
defined as recoverable (see the RECOVERABLE parameter), your 
DEFINE command will fail. 

primary [b secondary] 

specify the size of the primary and secondary extents to be allocated. 
Once the primary extent is filled, the space can expand to include a 
maximum of 13 additional secondary extents if you have specified a 
secondary allocation amount. 

primary and secondary can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n') form. Secondary allocation should be specified in 
case the catalog has to be extended. 

Abbreviations: CYL, REC, and TRK 
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Optional Parameters 



VOLUME( volser ) 

specifies tlie volume that is to contain the catalog. The volume cannot be 
currently owned by any other VSAM catalog. A user catalog can be 
defined on a mass storage volume. 

A volume serial number, volser, may contain one to six alphameric, 
national (@, #, and $), and special characters; the special characters 
include commas, blanks, semicolons, parentheses, slashes, asterisks, 
periods, quotation marks, ampersands, plus signs, hyphens, and equal signs. 
A volume serial number must be enclosed in single quotation marks if it 
contains a special character. Single quotation marks within a volume serial 
number must be coded as two single quotation marks. 

The VOLUME parameter interacts with other DEFINE CATALOG 
parameters. You should take care to ensure that the volume you specify for 
the catalog can satisfy the catalog's other attributes: 

. CYLINDERS, RECORDS, TRACKS: The volume contains enough 
unallocated space to satisfy the catalog's primary space requirement. 
(Space on the volume might already be allocated to nonVSAM data sets 
and system data sets. However, the volume cannot be owned by another 
VSAM catalog — that is, no space on the volume can already be 
allocated to VSAM objects.) 

• FILE: The volume information supplied with the DD statement is 
consistent with the information specified for the catalog and its 
components. 

Abbreviation: VOL 



ATTEMPTS( number \ 2 ) 

specifies the maximum"number of times the operator can try to enter a 
correct password in response to a prompting message. 

number 

is an integer from to 7 and can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n') form. If is specified, the operator 
is not prompted and is not allowed to enter a password from the 
console. 

Note to TSO Users: At a TSO Terminal the logon password is checked first 
before the user is prompted to supply a password for the catalog. Checking 
the logon password counts as one attempt to obtain a password. If 
ATTEMPTS is not specified, the user has one attempt to supply the 
catalog's password, because the default is 2. 

Abbreviation: ATT 

AUTHORIZATION( entrypoint [b string ] ) 

specifies that a user-security-verification routine (USVR) is available for 
additional security verification. When a protected catalog is accessed and 
the user supplies a correct password other than the catalog's master 
password, the USVR receives control. See "User- Written Exit Routines" in 
OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide for 
information on the user-security- verification routine. 
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entrypoint 
I specifies the name of the USVR. entrypoint can contain 1 to 8 

alphameric characters (A through Z, and through 9), or national 
characters (@,#,$), and special characters (the hyphen (-) and the 12-0 
overpunch (X'CO')). The name's first character is either an alphabetic or 
a national character. 

string 

specifies information to be passed on to the USVR when it receives 
control to verify authorization, string can contain 1 to 255 EBCDIC 
characters. 

When the string contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the string in single-quotation marks (for 
example, AUTHORIZATION ( entrypoint, '*DORIS*')). 

When the string contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, AUTHORIZATION (enrrj^omr, 
'*CA"ROL*')). 

You can code string in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
AUTHORIZATION(e«rr>pomr, X'E2E4C5') is the same as 
AUTHORIZATION(enrrj^omf, SUE). .The string can contain up to 255 
hexadecimal characters when expressed in this form, resulting in up to 
^ 128 bjftes of information. 

y Abbreviation: AUTH 

BUFFERSPACE( size \ 3072 ) 

specifies the minimum space, in bytes, to be provided for buffers when 
using the catalog. Decimal values you can specify are 3072, 4096, 5120, 
6144, 7168, and 8192. 

size 

is the amount of space, in bytes, to be provided for buffers, size can be 
expressed in decimal (n), hexadecimal (X'n'), or binary (B'n') form. 

Abbreviation: BUFSPor BUFSPC 

CODE( code ) 

specifies a code name for the catalog being defined. If an attempt is made 
to access a password-protected catalog without a password, the code name 
is used in a prompting message; the code enables the operator to be 
prompted for the password without disclosing the name of the catalog. If 
CODE is not specified, the operator is prompted with the name of the 
catalog. 

code 

can contain 1 to 8 EBCDIC characters. When the code contains a 
special character (that is, a comma [,], semicolon [;], blank [b], period 
[.], single quote ['], ampersand [ & ], plus sign [+], equal sign [=], 
hyphen [-], parenthesis [( or )], slash [/], or asterisk [*]), enclose the 
code in single-quotation marks (for example, CODEC*DORIS*'). 

I 
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When the code contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, CODE('*CA"ROL*'))- 

You can code code in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, CODE 
(X'E2E4C5') is the same as CODE(SUE). 

CONTROLPW( password ) 

specifies a control password for the catalog being defined. The control 
password permits the same operations as the update password. 

If a read or update password is the only password specified for the catalog, 
it (the highest-level password) propagates upward and becomes the 
password for all higher levels. When the master password is specified but 
the control password is not specified, the control password is null. 

password 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote [*], ampersand [ & ], 
plus sign [+], equal sign [=]. hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, CONTROLPW('*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, CONTROLPWC*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
CONTROLPW(X'E2E4C5') is the same as CONTROLPW(SUE). 

Abbreviation: CTLPW 

DESTAGEWAIT | NODESTAGEWAIT 

specifies whether a user catalog that is stored on a mass storage volume is 
to be destaged synchronously or asynchronously with respect to the 
program that closes it. 

DESTAGEWAIT 

indicates that destaging is to be completed before control is returned 
from VSAM to the program that issues the CLOSE macro. VSAM can 
thus notify the program whether destaging was successful. 

Abbreviation: DSTGW 

NODESTAGEWAIT 

indicates that notification of unsuccessful destaging is to be made only 
by a message to the operator. 

Abbreviation: NDSTGW 

If the user catalog is not stored on a mass storage volume, the attribute is 
ineffective until the direct access storage volume the catalog is stored on is 
converted to a mass storage volume (by way of the CONVERTV 
command, which is described in OS/VS Mass Storage System (MSS) 
Services: Reference Information). 

If one of these parameters is specified for the data component of a catalog 
and the other parameter is specified for the index component, the 
parameter specified for the index component applies to both components, 
because the sequence set of the index of a catalog is imbedded in the data. 
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FILE( dname ) 

' specifies the name of the DD statement that identifies the device and 
volume to be used for the catalog. The DD statement should specify 
DISP=OLD to prevent premature space allocation on the volume. If FILE 
is not specified and the catalog's volume is physically mounted, the volume 
identified with the VOLUME parameter is dynamically allocated. The 
volume must be mounted as permanently resident or reserved. 

MASTERPW( password ) 

specifies a master password for the catalog being defined. A catalog must 
be master password protected in order to password protect any VSAM 
data sets cataloged in it. The AUTHORIZATION, CODE, and 
ATTEMPTS parameters have no effect unless the catalog has a master 
password associated with it. The master password allows all operations; it 
is required to open the catalog as a data set. 

If a master password is not specified for the catalog, the catalog's 
highest-level password propagates upward and becomes the password for 
all higher levels, including the master password. The master password is 
null when no other passwords are specified. 

password 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [fe], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, MASTERPW('*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, MASTERPWC*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
MASTERPW(X*E2E4C5') is the same as MASTERPW(SUE). 

Abbreviation: MRPW 

MODEL( entryname [ / password ][ fe catname [ / password ]] ) 

specifies that an existing master or user catalog is to be used as a model for 
the user catalog being defined. For details about how a model is used, see 
"How to Use One Object as a Model for Another Object." 

It is possible to use an already defined master or user catalog as a model 
for another user catalog. When one entry is used as a model for another, its 
attributes are copied as the new entry is defined. You may use some 
attributes of the model and override others by explicitly specifying them in 
the definition of the user catalog. 

If a model is used, you must specify certain parameters even though no 
attributes are to be changed or added. The name of the user catalog to be 
defined and volume and space information always must be specified as 
parameters of USERCATALOG. 

entryname 

specifies the name of the master or user catalog to be used as a model. 
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password 

specifies a password. If the catalog to be used as a model is password 
protected, a password is required. If you specify both passwords (that is, 
the password following entryname and the password following catname), 
the password following catname is used for authorization. If the 
protection attributes are to be copied, enter the master password of the 
catalog being used as a model. If passwords are not to be copied, any 
password except the master can be used. 

catname 

specifies the name of the catalog to be used as a model. This parameter 
is required if the model catalog is neither the master catalog nor a 
catalog identified by a JOBCAT or STEPCAT DD statement. 

OWNER( ownerid ) 

specifies the identification of the owner of the catalog being defined. The 
ownerid may contain one to eight EBCDIC characters. 

ownerid 

can contain 1 to 8 EBCDIC characters. 

When the ownerid contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersand [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the ownerid in single-quotation marks (for 
example, OWNERC*DORIS*')). 

When the ownerid contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, OWNERC*CA"ROL*')). 

You can code ownerid in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
OWNER(X'E2E4C5') is the same as OWNER(SUE). 

READPW( password ) 

specifies a read password for the catalog being defined. The read password 
permits the user to list the catalog's entries (passwords and protection 
attributes are listed only when the master-level password is supplied). 

password 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [,], 
semicolon [;], blank [b], period [.], single quote ['], ampersahd [ & ], 
plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], 
or asterisk [*]), enclose the password in single-quotation marks (for 
example, READPW('*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, READPW('CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
READPW(X'E2E4C5') is the same as READPW(SUE). 

Abbreviation: RDPW 

RECOVERABLE | NOTRECOVERABLE 

specifies that a catalog recovery space is to be created on each volume 
owned by the catalog. 
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On the catalog's volume, the catalog recovery space is allocated from the 
I catalog's data space. On subsequent volumes owned by the catalog, the 

p catalog recovery space is allocated from the first data space defined on the 

volume. Primary allocation for a CRA is one cylinder. Once a primary 
extent is filled, the CRA can expand to include a maximum of 15 
additional extents. Allocation for each secondary extent is one cylinder. 
The number of records a CRA can contain varies with the device type (for 
example, for a 3330 with 20 control intervals per track, each extent will 
accommodate approximately 370 records). 

Abbreviatioiis: RVBL and NRVBL 

TO( date ) | FOR( days ) 

specifies the retention period for the catalog being defined. If no value is 
coded, the catalog can be deleted whenever it is empty. 

TO( date ) 

specifies the date, in the form yyddd, where yy is the year and ddd is the 
number (001 through 365) of the day, through which the catalog being 
defined is to be kept. 

FOR( days ) 

specifies the number of days for which the catalog being defined is to be 
kept. The maximum number that can be specified is 9999. If the number 
specified is through 1830, the catalog is retained for the number of 
days specified; if the number is between 1831 and 9999, the catalog is 
retained through the year 1999. 

days 
^ can be expressed in decimal (n), hexadecimal (X'n'), or binary (B'n') 

form. 

/ 

UPDATEPW( password ) 

specifies an update password for the catalog being defined. The update 
password permits entries to be added to the catalog being defined. The 
catalog must be update password prdtected in order to prevent 
unauthorized users from cataloging data sets. 

When you anticipate using the catalog to contain many nonVSAM entries, 
you should consider allowing the catalog's update password to be null (that 
is, to specify a master password but not an update password). A null 
update password allows you to alter and delete nonVSAM entries without 
having to supply the catalog's password. 

The phrase "an update- or higher-level password" means: 

• If the update password exists, you are required to correctly supply either 
the update, control, or master password before Access Method Services 
processing continues. 

• If the update password is null (that is, it does not exist), no. prompting 
message is issued and no password is required. 

You can protect the catalog and its VSAM entries by specifying a master 
password. You can allow the unrestricted alteration and deletion of 
nonVSAM entries and the addition of aU types of entries by not specifjring 
an update password. 

If a read password is the only password specified for the catalog (that is, it 

I is the highest-level password), it propagates upward and becomes the 

f 
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password for all higher levels. If you specify a higher-level password and 
do not specify an update or read password, the update password is null. 

password 

is a one- to eight-EBCDIC character password. 

When the password contains a special character (that is, a comma [J, 
semicolon [;], blank [h], period [.], single quote ['], ampersand [*], plus 
sign [+], equal sign [=], hyphen [-], parenthesis [( or )], slash [/], or 
asterisk [*]), enclose the password in single-quotation marks (for 
example, UPDATEPWC*DORIS*')). 

When the password contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, UPDATEPW('*CA"ROL*')). 

You can code password in hexadecimal form, where two hexadecimal 
characters- represent one EBCDIC character. For example, 
UPDATEPW(X'E2E4C5') is the same as UPDATEPW(SUE). 

Abbreviation: UPDPW 

WRITECHECK | NOWRITECHECK 

specifies whether the catalog is to be checked by a direct-access device 
operation called write-check when a record is written to the device. If 
WRITECHECK is specified, a record is written and then read, without 
data transfer, to test for the data check condition. 

Abbreviations: WCK and NWCK 



Attributes can be specified separately for the catalog's data and index 
components. 

DATA( optional parameters ) 

specifies the data component's attributes. If an optional parameter is not 
specified as a parameter of DATA, the data component shares the value or 
attribute specified for the catalog as a whole. 

Except for space allocation, attributes specified as parameters of DATA 
override the same attributes specified as parameters of USERCATALOG. 
Attributes specified as parameters of DATA also override the same 
attributes of a model catalog's data component. 

Parameters that can be specified for the catalog's data component are: 

• BUFFERSPACE: Specifies the amount of buffer space that the user's 
program is to provide from its address space when the program opens 
the data component as a separate VSAM object. 

• CYLINDERS, RECORDS, or TRACKS: You can specify an amount of 
space to be allocated to the data component. You must also specify an 
amount of space for the catalog's data space. See the section "How 
Space is Assigned to a Catalog" for a description of the significance of 
specifying space allocation as a parameter of DATA. 

• RECOVERABLE or NOTRECOVERABLE: Specifies whether a 
catalog recovery area is to be created on each volume owned by the 
catalog. 

. WRITECHECK or NOWRITECHECK: Specifies whether the catalog's 
records are to be checked by the direct-access device when they are 
written into the data component. 
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. DESTAGEWAIT or NODESTAGEWAIT: Specifies whether the 
catalog's data component, stored on a mass storage volume, is to be 
destaged synchronously or asynchronously with respect to the program 
that closes it. 

INDEX ( optional parameters ) 

specifies the index component's attributes. If an optional parameter is not 
specified as a parameter of INDEX, the index component shares the value 
or attribute specified for the catalog as a whole. 

Except for space allocation, attributes specified as parameters of INDEX 
override the same attributes specified as parameters of USERCATALOG. 
Attributes specified as parameters of INDEX also override the same 
attributes of a model catalog's index component. 

Parameters that can be specified for the catalog's index component are: 

• CYLINDERS, RECORDS, or TRACKS: You can specify an amount of 
space to be allocated to the index component. When you specify one of 
the space-quantity parameters as a parameter of INDEX, you must also 
specify a space-quantity parameter as a parameter of DATA. TRACKS, 
CYLINDERS, or RECORDS must have been specified as a parameter 
of DATA to be specified as a parameter of INDEX. See the section 
"How Space is Assigned to a Catalog" for a description of the 
significance of specifying space allocation as a parameter of DATA and 
INDEX. 

. DESTAGEWAIT or NODESTAGEWAIT: Specifies whether the 
catalog's index component, stored on a mass storage volume, is to be 
destaged synchronously or asynchronously with respect to the program 
that closes it. 

. WRITECHECK or NOWRTTECHECK: Specifies whether the index 
records are to be checked by the direct-access device when they are 
written into the index. 



The catalog parameter is used to supply the name and password, when 
required, of the master catalog when a user catalog is to be defined. 

CATALOG( mastercatname [/ password ] ) 

specifies the name and password of the master catalog. If the master 
catalog is password protected, its update- (or higher-level) password must 
be provided in this parameter or in response to prompting. 

mastercatname 

is the name of the master catalog that is required when a user catalog is 
being defined. 

password 

specifies the update- (or higher-level) password of the master catalog 
that is required when a user catalog is being defined, if the master 
catalog is password protected. 

Abbreviation: CAT 
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DEFINE USERCATALOG Examples 

Deflning a User Catalog and Determining the Catal(^*s Space Requirements: 
Example 1 



In this example, a user catalog is defined. The user catalog's data space is not 
available to contain other VSAM objects. The catalog is to be large enough to 
contain information about: 

100 key-sequenced clusters (that is, indexed VSAM data sets) 

10 entry-sequenced clusters (that is, sequential nonindexed VSAM data 
sets) 

5 key-sequenced clusters with alternate indexes to be upgraded 

5 entry-sequenced clusters with alternate indexes to be upgraded 

10 alternate indexes 

10 paths 

200 aliases 

10 generation data sets 

• 1000 nonVSAM data sets. 

• 5 volumes (the number to be controlled by the catalog). Each volume is a 
3330 volume and contains 20 data spaces. 

To determine how much space, in records and tracks, is required for the 
primary allocation of a to-be-defined catalog in your system, see the section, 
"Estimating the Catalog's Space Requirements." The number of records for 
the primary allocation of the catalog in this example is shown in the 
completed worksheet in Figure 9. 

When you define the catalog's space parameters, use the following format: 



DEFINE USERCATALOG - 

( TRACKS ( prim seen ) 



where: 



prim = the minimum amount of space for the catalog data-space's primary 
allocation. In this example, all of the data space is assigned to the catalog 
itself. The calculated value of prim should be rounded upward to the next 
whole number of tracks which is an even multiple of the catalog allocation 
unit for the device type being used (see the section "How Space is 
Assigned to a Catalog" for the size of an allocation unit). 

Because the catalog resides on a 3330 volume, the value of prim is: 
prim = .09N + 3 = 152.4 = = 153 tracks 

seen = the minimum amount of space for each secondary extent of the 
catalog's data space. 

The number of tracks required for the catalog's primary extent is at least 
153. This figure is an even multiple of an allocation unit for a 3330 device 
(three); therefore, no further rounding is necessary. If VSAM extends the 
catalog, it should extend it in increments of 18 tracks. 
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Variable Quantities 
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Figure 9. Completed Worksheet for Determining a Catalog's Space Requirements 

//DEFCAT 1 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

DEFINE USERCATALOG ( - 

NAME(MYCAT) - 

VOLUME(VSER04 ) - 

NOTRECOVERABLE - 

TRACKS( 153 18 ) ) - 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in aU Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 
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The DEFINE USERCATALOG command defines a user catalog. Its 
parameters are: 

• NAME, which specifies the name of the catalog, MYCAT. 

• VOLUME, which specifies that the catalog is to reside on the volume 
whose serial number is VSER04. 

• NOTRECOVERABLE, which specifies that no recovery space is to be 
allocated for this catalog. 

• TRACKS, which specifies that the catalog's data space is to be 153 tracks. 
When the user catalog is extended, VSAM extends it in increments of 18 
tracks. 

• Values and attributes that apply by default to the catalog are: 

- BUFFERSPACE = 3072 bytes 

- ATTEMPTS = 2 

- NOWRITECHECK 

- NODESTAGEWAIT 

• Null attributes and values of the catalog are: 

- All passwords 

- CODE 

- AUTHORIZATION 

- TO and FOR 

- OWNER 



Define a User Catalog Leaving Available Suballocatable Space: Example 2 



In this example, a user catalog is defined. The catalog will actually occupy 
only a portion of the space defined, leaving the remainder of the space 
available for the suballocation of other VSAM data sets. 

//DEFCAT2 JOB 

//STEP1 EXEC PGM=IDCAI'1S 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

DEFINE USERCATALOG( - 

NAME(D27UCAT1 ) - 
MASTERPW(MRPWD27 ) - 
UPDATEPW( UPPWD27 ) - 
FOR(365) - 
CYLINDERS! 150 5 ) - 
VOLUME( VSER02 ) ) - 
DATA{ - 

CYLINDERS ( 8 5))- 
INDEX( - 

CYLINDERS(5) ) - 
CATALOG ( AMASTCAT/MRCATPW2 ) 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 
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DEFINE USERCATALOG 

The DEFINE USERCATALOG command defines a user catalog, 
D27UCAT1. Its parameters are: 

• NAME, which names the user catalog, D27UCAT1. 

. MASTERPW and UPDATEPW, which specify master and update 
passwords for the catalog: MRPWD27 and UPPWD27. 

• FOR, which specifies that the user catalog is to be retained for 365 days. 

• CYLINDERS, which specifies that 150 cylinders are to be allocated for the 
user catalog's data space. When the user catalog's data space is extended, it 
is to be extended in increments of 5 cyhnders. 

• VOLUME, which specifies that the catalog is to reside on volume 
VSER02. Volume VSER02 will be dynamically allocated. 

. DATA and INDEX, which specify that VSAM is to allocate 13 cylinders 
for the catalog itself. VSAM determines the proportion of space that is 
allocated to the catalog's data and index components. The remainder of the 
catalog's data space (137 cylinders) is available to contain VSAM objects 
that reside in a nonunique data space. If the catalog's data component is 
extended, it is to be extended in increments of 5 cylinders. The catalog's 
index component is never extended. 

• CATALOG, which specifies that the user-catalog connector entry is to be 
defined in the master catalog, AMASTC AT. CATALOG provides the 
catalog's update password, MRCATPW2, so that the operator is not 
prompted to provide it. 

• Values and attributes that apply by default to the catalog are: 

- BUFFERSPACE = 3072 bytes 

- ATTEMPTS = 2 

- NOTRECOVERABLE 

- NOWRITECHECK 

- NODESTAGEWAIT 

• NuU attributes and values of the catalog are: 

- CONTROLPW and READPW passwords 

- CODE 

- AUTHORIZATION 

- OWNER 
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Define a User Catalog Using the MODEL Parameter: Example 3 



In this example, the user catalog defined previously, D27UCAT1, is used as a 
model for the user catalog being defined, D27UCAT2, 

//DEFCAT3 JOB 

//STEP1 EXEC PGM=IDCAMS 

//STEPCAT DD DSNAME=D27UCAT1 ,DISP=SHR 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

DEFINE USERCATALOG( - 

NAME( D27UCAT2 ) - 

MASTERPW(MASTD27) - 

UPDATEPW(UPDD27) - 

CYLINDERS (50 5) - 

VOLUME( VSER03 ) - 

MODEL(D27UCAT1/MRPWD27 - 
D27UCAT1/MRPWD27 ) ) - 
CATALOG! AMASTCAT/MRCATPW2 ) 
/* 

The job control language statements are: 

• STEPCAT DD, which makes a catalog available for this job step: 
D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DEFINE USERCATALOG command defines catalog D27UCAT2. Its 
parameters are: 

. NAME, which names the catalog, D27UCAT2. 

. MASTERPW and UPDATEPW, which specify master and update 
passwords for the catalog: MASTD27 and UPDD27 

. CYLINDERS, which specifies that 50 cylinders are to be allocated for the 
catalog's data space. The catalog itself will reside within this data space. 
When the catalog's data space is extended, it is to be extended in 
increments of 5 cylinders. 

• VOLUME, which specifies that the catalog is to reside on volume 
VSER03. Volume VSER03 will be dynamically allocated. 

• MODEL, which identifies D27UCAT1 as the catalog to use as a model for 
D27UCAT2. The attributes and specifications of D27UCAT1 that are not 
otherwise specified with the above parameters are used to define the 
attributes and specifications of D27UCAT2. D27UCAT1 contains the 
catalog entries that describe itself (the master catalog, AMASTCAT, 
contains a user-catalog connector entry which points to 
D27UCAT1) — this is why D27UCAT1 is specified as MODEL'S catname 
subparameter. Values and attributes that apply to D27UCAT2 as a result 
of using D27UCAT1 as a model are: 

- FOR = 365 days (retention period) 

- CYLINDERS = 8 (primary) and 5 (secondary) for the data component 
and 5 (primary) for the index component 

- BUFFERSPACE = 3072 bytes 

- ATTEMPTS = 2 

- NOTRECOVERABLE 
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- NOWRITECHECK 

- NODESTAGEWATT 

- CONTROLPW and READPW passwords are null 

- CODE is null 

- AUTHORIZATION is null 

- OWNER is nuU 

• CATALOG, which specifies that the user catalog connector is to be 
defined in the AMASTCAT catalog. The update password of 
AMASTCAT is MRCATPW2. 

DeHne a Recoverable User Catalog: Example 4 

In this example, a recoverable user catalog is defined. 

//DEFCAT4 JOB 

//STEP1 EXEC PGM=IDCAMS 

//V0L1 DD VOL=SER=VSER01 ,UNIT=2314,DISP=OLD 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

DEFINE USERCATALOG( - 

NAME(D64CAT) - 

MASTERPW( UCATMRPW ) - 

UPDATEPW( UCATUPPW ) - 

T0( 99999) - 

ATTEMPTS ( 3) - 

CODEC BEQUIET ) - 

RECOVERABLE - 

TRACKS(300) - 

FILECVOLI ) - 

VOLUME(VSER01 ) ) - 
DATA( - 

RECORDS! 500 1 00 ) ) 
/* 

The job control language statements are: 

• VOLl DD, which describes the volume on which the catalog is to be 
defined. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method- Services messages to the programmer are to be sent. 

The DEFINE USERCATALOG command defines a user catalog, D64CAT. 
Its parameters are: 

• NAME, which names the user catalog, D64CAT. 

• MASTERPW and UPDATEPW, which specify master and update 
passwords for the catalog: UCATMRPW and UCATUPPW. 

• TO, which specifies that the user catalog is to be retained until it is 
deleted (that is, the user catalog does not have a retention period). 

• ATTEMPTS, which specifies that the operator is prompted for the correct 
password up to three times. 

• CODE, which specifies that the catalog is identified, in the prompting 
message to the operator, with the name "BEQUIET." 
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• RECOVERABLE, which specifies that the catalog's volumes contain 
catalog recovery areas and the LISTCRA, EXPORTRA, IMPORTRA, and 
RESETCAT commands can be used to restore entries in the catalog. 

• TRACKS, which specifies that 300 tracks are to be allocated for the user 
catalog's data space. No secondary allocation is specified. If additional 
VSAM space is required on the volume, it can be explicitly defined using 
the DEFINE SPACE command. 

• FILE, which points to the VOLl DD statement. The VOLl DD statement 
directs the OS/VS Scheduler to mount and aUocate the volume on which 
the user catalog is to reside. In this example, the volume is not dynamically 
allocated. 

• VOLUME, which specifies that the user catalog is to reside on volume 
VSEROL 

• DATA, which specifies that VSAM is to allocate space to accommodate 
500 records for the user catalog. VSAM determines the total amount of 
space that is allocated to the catalog's data and index components. The 
remainder of the catalog's data space is available to contain the catalog 
recoverable area (CRA) and other VSAM objects that reside in a 
nonunique data space. If the catalog's data component is extended, it is 
extended in increments to accommodate 100 records. 

You may wish to estimate the amount of space which VSAM will actually 
allocate to the catalog in order to: 

- Ensure that the total amount of space specified via TRACKS is large 
enough 

- Determine how much suballocatable space will be available. 

You can make the computation by using the algorithms provided in the 
section "Estimating the Catalog's Space Requirements." Because the 
catalog resides on a 2314, the total amount of space wiU be: 

aN + b = (.1116 X 500) + 4 = 59.8 = 60 tracks 

• Values and attributes that apply by default to the catalog are: 

- BUFFERSPACE = 3072 bytes 
= NOWRITECHECK 

- NODESTAGEWAIT 

• Null attributes and values of the catalog are: 

- CONTROLPW and READPW passwords 

- AUTHORIZATION 

- OWNER 
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The format of the DELETE command is: 



DELETE 



( entryname {/ password\{h entryname [/password ]...]) 
[ALMS I 

ALTERNATEINDEX | 

CLUSTER I 

GENERATIONDATAGROUP | 

NONVSAM I 

PAGESPACE I 

PATH I 

SPACE I 

USERCATALOG] 
[ERASE I NOERASE] 
[YVVEidname)] 
[FORCE I NOFORCE ] 
[PURGE i NQPURGE ] 
[ SCRATCH I NOSCRATCH] 

[CATALOG( catname {/password ])] 



DELETE may be abbreviated: DEL. 



DELETE Parameters 
Required Parameters 



( entryname [/ password ][b entryname... ^) 

names the entries to be deleted. If more than one entry is to be deleted, the 
list of entry names must be enclosed in parentheses. This parameter must 
be the first parameter following DELETE. 

entryname 

is the name of the entry to be deleted, or the volume serial number of 
the volume that contains a data space to be deleted. See the section 
"Generic Name and DELETE" for a description of how to specify a 
generic name in order to delete multiple entries with one entryname. 

If you are deleting a member of a nonVSAM partitioned data set, the 
entryname must be specified in the format: pdsname(membername). 

password 

specifies a password for a password-protected entry. Passwords may be 
specified for each entry name or the catalog's password may be 
specified through the CATALOG parameter for the catalog that 
contains the entries to be deleted. Only certain types of catalog entries 
can be password-protected. To delete a 

• Alias, specify the catalog's update- (or higher-level) password. 

• Alternate index, specify its master password, or the catalog^ master 
password. 

• Cluster, specify its master password, or the catalog's master 
password. 
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Optional Parameters 



• Generation Data Group, specify the catalog's update- (or 
higher-level) password. 

• NonVSAM entry, specify the catalog's update- (or higher-level) 
password. 

• Pagespace, specify its master password, or the catalog's master 
password. 

• Path, specify its master password, or the catalog's master password. 

• Data space, specify the catalog's update- (or higher-level) password. 

• User catalog, specify its master password with the entryname (that is, 
Access Method Services does not issue a prompting message to the 
operator or TSO terminal user in this case). 



ALIAS I ALTERNATEINDEX | CLUSTER | 

GENERATIONDATAGROUP | NONVSAM | PAGESPACE | PATH | 
SPACE I USERCATALOG 

specifies the type of the object or entry to be deleted. If the object to be deleted 
is a catalog or data space, USERCATALOG or SPACE is required. 

ALIAS 

specifies that the entry to be deleted is an alias entry. 

ALTERNATEINDEX 

specifies that the object to be deleted is an alternate index and its data 
and index entries. When a path entry is associated with the alternate 
index, the path entry is also deleted. When the alternate index has the 
to-be-upgraded attribute and it is the only such alternate index 
associated with the base cluster, the base cluster's upgrade-set entry is 
also deleted. 

Abbreviation: AIX 

CLUSTER 

specifies that the object to be deleted is a cluster, its associated data and 
index entries, and any related paths and alternate indexes. 

Abbreviation: CL 

GENERATIONDATAGROUP 

specifies that the entry to be deleted is a generation data group entry. A 
generation data group can be deleted when it is empty, or when you 
specify the FORCE parameter. 

Abbreviation: GDG 

NONVSAM 

specifies that the entry to be deleted is a nonVSAM data set entry. If 
the nonVSAM data set has aliases, all of its ahas entries are deleted. If 
the nonVSAM data set is partitioned, you can delete one of its members 
by specifying pdsname (member name). 

Abbreviation: NVSAM 

PAGESPACE specifies that an inactive page space is to be deleted. A page 
space is identified as "active" during the operator's IPL procedure. 

Abbreviation: PGSPC 
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PATH 

specifies that a path entry is to be deleted. No entries associated with 
the path are deleted. 

SPACE 

specifies that all empty VSAM data spaces on a volume are to be 
deleted. This parameter is required when you want to delete the 
volume's empty data spaces. A data space can be deleted when it is 
empty, or when you specify the FORCE parameter. If all data spaces on 
the volume have been deleted and the volume is not a candidate or 
catalog volume, its volume entry is also deleted. (Note: When a volume 
entry in the catalog is deleted, VSAM's ownership of the volume is 
relinquished.) When the catalog that owns the volume is recoverable, 
the data space that contains the volume's recovery area is not deleted 
unless all other data spaces on the volume have been deleted. 

Abbreviation: SPC 

USERCATALOG 

specifies that the object to be deleted is a user catalog. The catalog 
connector entry in the master catalog is deleted. If the user catalog has 
aliases, all of the catalog's alias entries in the master catalog are deleted. 
This parameter must be specified if a user catalog is to be deleted. 

A user catalog can be deleted when it is empty (that is, it contains only 
its self -describing entries and its volume's volume entry), or when you 
specify the FORCE parameter. 

Abbreviation: UCAT 

CATALOG( catname [/ password ] ) 

specifies the name of the catalog that contains the entries to be deleted. 
See "Order of Catalog Use: DELETE" for information about the order in 
which catalogs are searched. This parameter cannot be used when a user 
catalog is to be deleted. 

catname 

identifies the catalog that contains the entry to be deleted. 

password 

specifies the password of the catalog that contains the entries to be 
deleted. If entries to be deleted are password protected and the catalog 
is also password protected, a password must be supplied either through 
CATALOG or with the name of each entry to be deleted. The password 
which must be specified for each entry type is given under the 
description of the entryname parameter. If a password is supplied 
through the CATALOG parameter, it takes precedence over any 
password supplied with the entryname parameter and is used for all 
entries to be deleted. If a user catalog is to be deleted, a password, if 
required, must be supplied with the entryname. 

Abbreviation: CAT 
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ERASE ! NOERASE 

specifies whether the data component of a cluster or alternate index to be 
deleted is to be erased, that is, overwritten with binary zeros. This 
parameter will override whatever was coded when the cluster or alternate 
index was defined or last altered. This parameter should be specified only 
when a cluster or alternate index entry is to be deleted. When you specify 
ERASE, you must identify the to-be-deleted entry's catalog with a 
JOBCAT or STEPCAT DD statement unless 

• The entry is in the master catalog, or 

• The first qualifier in the entry's qualified name identifies the catalog 
(that is, the first qualifier is the catalog's name or alias). 

ERASE 

specifies that the data component is to be overwritten with binary zeros 
when the cluster or alternate index is deleted. If ERASE is specified, the 
volume that contains the data component must be mounted. 

Abbreviation: ERAS 

NOERASE 

specifies that the data component is not to be overwritten with binary 
zeros when the cluster or alternate index is deleted. 

Abbreviation: NERAS 

FILE( dname ) 

specifies the name of the DD statement that identifies: 

• The volume that contains a unique data set to be deleted. 

• The volume that contains a nonVSAM data set to be deleted (with 
SCRATCH). 

• The entry (data set) to be deleted if erase processing is to be performed. 
(Note: For erase processing, a JOBCAT or STEPCAT DD statement is 
required unless the data set is cataloged in the master catalog or its high 
level qualifier is the name or alias of the catalog containing the entry.) 

• The volume that contains the data space to be deleted, 

• The partitioned data set from which a member (or members) is to be 
deleted. 

• The catalog recovery volume(s) when the entry being deleted is in a 
recoverable catalog. If the volumes are of a different device type, 
concatenated DD statements must be used. (The catalog recovery 
volume is the volume whose recovery space contains a copy of the entry 
being deleted. See "Deleting Catalog Entries" for more details on 
catalog recovery volume mounting requirements.) 

• The volume(s) owned by the catalog when you delete a catalog using 
the FORCE option. 

When more than one volume is to be identified (for example, a 
multivolume data set), FILE identifies the DD statement which specifies all 
volumes. If, in any of the above cases the volumes are of a different device 
type, concatenated DD second DELETE statements must be used. 

If you do not specify FILE and VSAM requires access to a volume or 
volumes during the delete processing, the volume(s) will be dynamically 
allocated. When erase processing is to be performed, the entryname will be 
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. dynamically allocated if FILE is not specified. Dynamic allocation requires 
that the volume(s) must be mounted as permanently resident or reserved. 

FORCE I NOFORCE 

The FORCE parameter allows you to delete data spaces, generation data 
groups, and VSAM user catalogs without first ensuring that these objects 
are empty. 

• When you delete space using the FORCE parameter, all VSAM data 
spaces on the volume(s) are scratched from the VTOC. VSAM's 
ownership of the volume(s) is given up. Before the data spaces are 
scratched, VSAM verifies that no VSAM clusters on the volume are 
open. The clusters remain cataloged, but their entries are marked 
unusable. Subsequently, you can delete the cluster from the catalog. 

You cannot specify FORCE to delete the space on a volume that 
contains the VSAM master catalog or a user catalog. When you specify 
FORCE, you must supply the master password of the catalog that 
contains the volume's entry. 

• When you" delete a user catalog using the FORCE parameter, the 
catalog is deleted even though it contains catalog entries for objects that 
haven't been deleted. All data spaces are deleted from each volume 
owned by the catalog. Before the data spaces are scratched, VSAM 
verifies that no VSAM clusters on the volume are open. The volumes 
are available to be used by the OS/VS2 MVS system or to be assigned 
to other VSAM catalogs. All cataloged objects are automatically 
deleted, but the contents of each cluster and alternate index are not 
erased. NonVSAM data set entries in the catalog are deleted, but the 
nonVSAM data set's space on the volume is undisturbed. The 
nonVSAM data set can be located with its DSCB in the volume's 
VTOC. VSAM clusters and alternate indexes, even though they might 
reside in unique data spaces, cannot be located, because the data space's 
DSCB is scratched when the catalog is deleted. 

When you delete a user catalog using the FORCE parameter, you must 
supply the master password of the catalog being deleted. 

• When you delete a generation data group using FORCE, the GDG entry 
is deleted even though it might point to generation data sets (that is, it 
might point to nonVSAM entries in the catalog). Each nonVSAM data 
set entry (that is, the entry for a generation data set) pointed to by the 
GDG base entry is deleted before the GDG base entry is deleted. 
However, the nonVSAM data set's space and contents on the volume is 
undisturbed. The data set can be located with its DSCB in the volume's 
VTOC. 

NOFORCE, the default option, causes the DELETE command to 
terminate when you request the deletion of a nonempty data space, 
generation data group, or catalog. 

Abbreviations: FRC and NFRC 

PURGE I NOPURGE 

specifies whether the entry is to be deleted regardless of the retention 
period specified. This parameter cannot be used if a data-space entry is to 
be deleted. 
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PURGE 

specifies that the entry is to be deleted even if the retention period, 
specified in the TO or FOR parameter, has not expired. 

Abbreviation: PRG 

NOPURGE 

specifies that the entry is not to be deleted if the retention period has 
not expired. If NOPURGE is coded and the retention period has not 
expired, the entry is not deleted. 

Abbreviation: NPRG 

SCRATCH I NOSCRATCH 

has two uses: 

1. With NONVSAM, SCRATCH | NOSCRATCH specifies whether a 
nonVSAM data set is to be scratched — removed from the VTOC — of 
the volume on which it resides. 

2. With CLUSTER, ALTERNATEINDEX, SPACE, or PAGESPACE, 
NOSCRATCH specifies that the entry is to be deleted from the catalog 
without access to the volume that contains the object defined by the 
entry. NOSCRATCH cannot be specified for VSAM clusters, alternate 
indexes, or page spaces in recoverable catalogs. See the section "VSAM 
Catalog Cleanup" in the chapter "Data Security and Protection" for 
important information about the use of DELETE NOSCRATCH. 

When you specify SCRATCH, you must identify the to-be-deleted entry's 
catalog with a JOBCAT or STEPCAT DD statement, unless: 



The entry is in the master catalog, or 



• The first qualifier in the entry's qualified name identifies the catalog 
(that is, the first qualifier is the catalog's name or alias). 

You should specify NOSCRATCH if the format- 1 DSCB of a nonVSAM 
data set has already been scratched from the VTOC. 

You should specify NOSCRATCH if you are deleting a nonVSAM data set 
which was defined with an esoteric device type (for example, SYSDA). If 
you specify SCRATCH, your DELETE will fail. You should use the 
SCRATCH function of the OS/VS utiUty, lEHPROGM, to remove the 
format- 1 DSCB from the VTOC. 

Abbreviations: SCR and NSCR 
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DELETE Examples 

Deleting a Key-Sequenced VSAM Cluster: Example 1 

In this example, a key-sequenced duster is deleted. Alternate indexes and 
paths related to the key-sequenced cluster are deleted automatically by 
Access Method Services. Access Method Services wUl dynamically allocate 
the key-sequenced data set so that the data can be overwritten (as specified 
by the ERASE option). 

//DELET1 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DELETE - 

D40. EXAMPLE. KSDS1 - 

PURGE - 

ERASE - 

CATALOG! D27UCAT2/MRPWD27 ) 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DELETE command deletes the key-sequenced VSAM cluster from the 
D27UCAT2 catalog. Its parameters are: 

• D40.EXAMPLE.KSDS1, which is the entryname of the object being 
deleted. D40.EXAMPLE.KSDS1 is a key-sequenced VSAM cluster. 

• PURGE, which specifies that the cluster is to be deleted regardless of its 
retention period or date. 

• ERASE, which specifies that the cluster's data component is to be 
overwritten with binary zeros, regardless of a NOERASE attribute that 
might have been specified when the cluster was defined or altered. 

• CATALOG, which identifies the catalog that contains the cluster's entries, 
D27UCAT2. The catalog's master password is required, unless the entry's 
master password is specified with the entryname. 
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Deleting an Entry-Sequenced VSAM Cluster and Ail Empty Data Spaces On a 
Volume: Example 2 



In this example, an entry-sequenced VSAM cluster is deleted. Alternate 
indexes and paths related to the entry-sequenced cluster are automatically 
deleted by Access Method Services. Next, all empty VSAM data spaces on 
volume VSER03 are deleted and the volume's volume entry is deleted. 

//DELET2 JOB . . . 

//JOBCAT DD DSNAME=D27UCAT2,DISP=OLD 
//STEP1 EXEC PGM=IDCAMS 

//DD2 DD VOL=SER=VSER03,UNIT=3330,DISP=OLD 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DELETE - 

EXAMPLE. ESDS2/DEPT26M - 

PURGE - 

CLUSTER 
DELETE - 

VSER03 - 

SPACE - 

FILE ( DD2 ) 
/* 

The job control language statements are: 

• JOBCAT DD, which makes a catalog available for the job: D27UCAT2. 

. SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The first DELETE command deletes the only VSAM cluster on volume 
VSER03. The DELETE command's parameters are: 

• EXAMPLE.ESDS2, which is the entryname of the cluster to be deleted, 
and DEPT26M, which is the cluster's master password. 

• PURGE, which specifies that the cluster is to be deleted regardless of its 
retention period or date. Alternate indexes and paths related to the 
entry-sequenced cluster are also deleted regardless of their retention 
periods or dates. 

• CLUSTER, which specifies that the entryname EXAMPLE.ESDS2 
identifies a VSAM cluster (that is, the entryname identifies a cluster entry). 

The second DELETE command causes VSAM to examine each data space 
cataloged in the volume's entry and, if the data space is empty, delete the data 
space. VSAM deletes the volume entry when there are no data spaces 
cataloged in it and when there are no data sets identified that specify the 
volume as a candidate volume. VSAM also updates the volume's VTOC to 
reflect the deleted data spaces. The DD2 DD statement ensures that volume 
VSER03 is mounted when its data spaces are deleted. In this example JCL 
has been used instead of allowing Access Method Services to dynamically 
allocate the volume. If the volume were mounted as permanently RESIDENT 
or RESERVED, Access Method Services could dynamically allocate the 
volume without the need of JCL or the FILE parameter. The DELETE 
command's parameters are: 

• VSER03, which identifies the volume that contains empty VSAM data 
spaces. 
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• SPACE, which specifies that the entryname identifies a volume entry. 

I When a volume's data spaces are to be deleted, the SPACE parameter is 

required. 

• FILE, which specifies the dname of a DD statement that describes the 
VSAM volume and causes it to be mounted. 

Deleting Two Key-Sequenced Clusters: Example 3 

In this example, two key-sequenced clusters, MYDATA and ENTRY, are 
deleted from a recoverable catalog. This example illustrates how more than 
one cataloged object is deleted with a single DELETE command. 

//DELET3 JOB 

//JOBCAT DD DSNAME=MYCAT,DISP=SHR 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DELETE - 

(D40. MYDATA - 

ENTRY ) - 

PURGE - 

CLUSTER 
/* 

The job control language statements are: 

• JOBCAT DD, which makes the catalog MYCAT available for the job. 

' • SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
n^ Method Services messages to the programmer are to be sent. 

/ The DELETE command deletes the key-sequenced clusters D40.MYDATA 

and ENTRY. The high-level qualifier of the object D40.MYDATA causes the 
catalog D27UCAT1 to be searched, since it is assumed that D40 is an alias of 
the catalog D27UCAT1. The object ENTRY is found in the catalog MYCAT, 
which is made available to the job through the JOBCAT DD statement. Both 
entries wiU be dynamically allocated so that their respective catalog recovery 
areas can be updated. The DELETE command's parameters are: 

. D40.MYDATA and ENTRY, which identify the objects to be deleted. 
D40. MYDATA and ENTRY are the entrynames of two key-sequenced 
clusters. It is assumed that neither cluster is password-protected at this 
time. If either cluster is password-protected, the operator is prompted to 
supply the cluster's master password. 

• PURGE, which specifies that the cluster is to be deleted regardless of its 
retention period or date. 

. CLUSTER, which specifies that D40.MYDATA and ENTRY are clusters 
(that is, the names identify cluster catalog records). 
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Deleting a NonVSAM Data Set's Entry: Example 4 



In this example, a nonVSAM data set's entry (cataloged in a VSAM user 
catalog) is deleted. The SCRATCH parameter is implied (that is, it is the 
default). A FILE parameter and its associated DD statement are provided to 
allocate the data set's volume. In this example, dynamic allocation is not used 
to provide catalog or volume allocation. 

//DELET4 JOB 

//JOBCAT DD DSNAME=D27UCAT1,DISP=SHR 
//STEP1 EXEC PGM=IDCAMS 

//DD1 DD VOL=SER=VSER02,UNIT=2314,DISP=OLD, 
// DSNAME=EXAMPLE . NONVSAM 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DELETE - 

EXAMPLE . NONVSAM - 

FILE (DD1 ) - 

PURGE - 

CATALOG! D27UCAT1/UPPWD27 ) 
/* 

The job control language statements are: 

• JOBCAT DD, which makes a catalog available for this job: D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DELETE command deletes the nonVSAM data set 
EXAMPLE.NONVSAM. The DELETE command's parameters are: 

• EXAMPLE.NONVSAM, which is the entryname of the object to be 
deleted. 

• FILE, which specifies the dname of a DD statement that describes the 
nonVSAM data set's volume and causes it to be mounted. When the data 
set is deleted, its DSCB entry in the volume's VTOC is removed. 

• PURGE, which specifies that the nonVSAM data set's retention period or 
date is to be ignored. If PURGE is not specified and the nonVSAM data 
set's retention period has not yet expired, VSAM wouldn't delete its entry. 

• CATALOG, which identifies the catalog that contains the entries, 
D27UCAT1 , and its update password, UPPWD27. 
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Deleting Nonempty VSAM Data Spaces on a Volume: Example 5 

f In this example, all of the data spaces on volume VSER05 are deleted, 

whether or not they are empty. All VSAM data spaces on the volume are 
scratched from the VTOC and the ownership of the volume is surrendered by 
the catalog, AMASTCAT. Any clusters or alternate indexes contained within 
the data spaces on volume VSER05 are marked unusable in the catalog. 
Because all VSAM data spaces on the volume are deleted, the volume's 
catalog entry is also deleted. 

//DELET5 JOB 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DELETE - 

VSER05 - 

SPACE - 

FORCE - 

CATALOG( AMASTCAT/MRCATPW2 ) 
/* 

The job control language statements are: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DELETE command's parameters are: 

• VSER05, which identifies the volume with its serial number. Because the 
volume's VTOC must be updated, Access Method Services will 

^ dynamically allocate the volume. 



/ 



SPACE, which specifies that a volume entry is to be modified or deleted. 
When a volume's data space is to be deleted, the SPACE parameter is 
required. 

FORCE, which specifies that all VSAM data spaces on the volume are to 
be deleted, whether or not they are empty, and that volume ownership is to 
be released. 

CATALOG, which identifies the catalog that owns the volume, 
AMASTCAT. The catalog's update (or higher level) password is required. 



Deleting a User Catalog: Example 6 



In this example, a user catalog is deleted. A user catalog can be deleted when 
it is empty — that is, when there are no objects except the catalog's volume 
cataloged in it. If the catalog is not empty, it cannot be deleted unless the 
FORCE parameter is specified. 

//DELET6 JOB 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DELETE - 

D27UCAT1/MRPWD27 - 

PURGE - 

USERCATALOG 
/* 



I) 



r 
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The DELETE command deletes the catalog. The volume that contained the 
catalog is now available for ownership by another VSAM catalog. The 
DELETE command also deletes the catalog's user catalog connector entry in 
the master catalog. The DELETE command's parameters are: 

• D27UCAT1, the name of the user catalog. The catalog's update (or higher 
level) password is required. 

• PURGE, which specifies that the user catalog's retention period or date is 
to be ignored. If PURGE is not specified and the catalog's retention period 
has not yet expired, it won't be deleted. 



USERCATALOG, which identifies D27UCAT1 as a user catalog. 



Deleting an Alias Entry: Example 7 



In this example, an alias entry, EXAMPLE. NONVS AMI, is removed from 
catalog D27UC ATI. 

//DELET7 JOB 

//JOBCAT DD DSNAME=D27UCAT1 ,DISP=OLD 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DELETE - 

EXAMPLE. N0NVSAM1 - 

ALIAS - 

CATALOG ( D27UCAT1/MRPWD27 ) 
/* 

The job control language statements are: 

• JOBCAT DD, which makes a catalog available for this job: D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DELETE command removes an alias entry from catalog D27UCAT1. Its 
parameters are: 

. EXAMPLE.NONVSAMl, the entryname of the object to be deleted. 
EXAMPLE.NONVSAMl identifies an alias entry. 

• ALIAS, which specifies the type of entry to be deleted. VSAM verifies that 
EXAMPLE.NONVSAMl is an alias entry, then deletes it. If 
EXAMPLE.NONVSAMl incorrectly identified another entry by mistake, 
VSAM would not delete the entry, but would note the discrepancy with a 
message to the programmer. 

e CATALOG, which identifies the catalog that contains the entry, 
D27UCAT1, and its master password, MRPWD27. 
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Deleting GenericaOy-Naoaed Entries: Example S 

In this example, each catalog entry with the name "GENERIC*. ABLE" is 
deleted, where "♦" is any 1- to 8-character simple name. The name 
"GENERIC. *.ABLE" is a generic name, and this example shows how all 
catalog entries with the same generic name are deleted. 

//DELET8 JOB . . . 

//JOBCAT DD DSNAME=D27UCAT1 ,PISP=0LD 
//STEP! EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DELETE - 

GENERIC .*. ABLE -' 

PURGE - 

CATAL0G(D27UCAT1/MRPWD27 ) 
/* 

The job control language statements are: 

• JOBCAT DD, which makes a catalog available for this job: D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DELETE command removes all entries (and their associated entries) 
with the generic name "GENERIC.*.ABLE" from catalog D27UCAT1. Its 
parameters are: 

• GENERIC*. ABLE, a generic name, identifies all catalog entries with the 
name GENERIC*. ABLE. 



7 • PURGE, which specifies that each entry is to be purged regardless of the 

retention period or date specified when it was defined. 

• CATALOG, which identifies the catalog that contains the entries, 
D27UC AT 1 , and its master password, MRPWD27 . 

List a Generation Data Groii|i's Entries, Then Delete the Group and Its Data 
Sets: Example 9 

In this example, a generation data group, GDGOl, and its associated 
(generation data set) entries are listed. Next, the only generation data set in 
the group is deleted. Finally, the generation data group base catalog entry is 
deleted. 

//DELET9 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
LISTCAT - 

ENTRIES (GDGOl ) - 

ALL 
DELETE - 

GDGOl .GOOOIVOO - 

PURGE 
DELETE - 

GDGOl - 

GENERATIONDATAGROUP - 

PURGE 
/* 
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The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

Because no catalog was specified in a CATALOG parameter or with a 
JOBCAT or STEPCAT DD statement, VSAM assumes all entries required 
for this command sequence are in the master catalog. 

The LISTCAT command lists the generation data group GDGOl and its 
associated generation data set entries. Its parameters are: 

• ENTRIES, which specifies that the entry GDGOl is to be listed. Since the 
entry GDGOl is a generation data group entry, its associated generation 
data set's (nonVSAM) entries are also listed. In addition, if one of the 
generation data sets has aliases, the alias entries associated with the 
generation data set's entry are Usted. 

• ALL, which specifies that all fields are to be listed. 

The first DELETE command removes the nonVSAM data set entry for the 
only generation data set in the generation data group: GDGOl. GOOOIVOO. Its 
parameters are: 

• GDGOl. GOOOIVOO, the entryname of the object being deleted. 
GDGOl. GOOOIVOO identifies the only generation data set in the 
generation data group GDGOl. 

• PURGE, which specifies that the generation data set's retention period or 
date is to be ignored. If PURGE is not specified and the generation data 
set's retention period has not yet expired, VSAM wouldn't delete its entry. 

The second DELETE command removes the generation data group base 
catalog entry from the catalog. Its parameters are: 

• GDGOl, the entryname of the object being deleted. GDGOl identifies the 
generation data group base entry. 

• GENERATIONDATAGROUP, which specifies the type of entry to be 
deleted. VSAM verifies that GDGOl is a generation data group entry, then 
deletes it. If GDGOl incorrectly specified another type of entry, VSAM 
would not delete the entry, but would note the discrepancy with a message 
to the programmer. 

• PURGE, which specifies that the generation data group's retention period 
or date is to be ignored. If PURGE is not specified and the generation data 
group's retention period has not yet expired, VSAM wouldn't delete its 
entry. 
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Deleting a Member of a Partitioned (NonVSAM) Data Set: Example 10 

In this example, the MEMl member of partitioned data set 
EXAMPLE.NONVSAM2 is deleted. Next, the nonVSAM data set itself is 
deleted. 



//DELET10 


JOB 


... 


//JOBCAT 


DD 


DSNAME=D27UCAT1 ,DISP=SHR 


//STEP1 


EXEC 


PGM=IDCAMS 


//SYSPRINT DD 


SYSOUT=A 


//SYSIN 


DD 


* 


DELETE - 






EXAMPLE 


.N0NVSAM2(MEM1 ) - 




CATALOG! D27UCAT1 /MRPWD27 ) 


DELETE - 






EXAMPLE 


.N0NVSAM2 - 




PURGE - 






CATALOG ( D2 7UCAT 1 /MRPWD2 7 ) 


/* 







The job control language statements are: 

• JOBCAT DD, which makes a catalog available for this job: D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The first DELETE command deletes one of the members of a partitioned 
data set, EXAMPLE.NONVSAM2(MEMl), from the user catalog 
D27UCATL Its parameters are: 

. EXAMPLE.NONVSAM2(MEMl), which is the entryname of one of the 
members of the partitioned (nonVSAM) data set, 
EXAMPLE.NONVSAM2. The entryname identifies the object to be 
deleted. 

• CATALOG, which identifies the catalog that contains the entry, 
D27UCAT1, and its master password, MRPWD27. 

The second DELETE command deletes all remaining members, as well as the 
data set itself, of the partitioned nonVSAM data set 
EXAMPLE.NONVSAM2. Its parameters are: 

• EXAMPLE.NONVSAM2, which is the entryname of the object to be 
deleted. 

• PURGE, which specifies that the nonVSAM data set's retention period or 
date is to be ignored. If PURGE had not been specified and the nonVSAM 
data set's retention period has not yet expired, VSAM wouldn't delete its 
entry. 

• CATALOG, which identifies the catalog that contains the entry, 
D27UCAT1, and its master password, MRPWD27. 

In the second part of this example, the DSCB entry in the volume's VTOC is 
removed. Dynamic allocation is used to allocate the data set's volume. 
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Deleting a Page Space: Example 1 1 

In this example, page space SYS1.PAGE2 is deleted. 

//DELET11 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DELETE - 

SYS 1 . PAGE2 - • 

PURGE - 

PAGESPACE 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in aU Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DELETE command removes a page space entry, SYS1.PAGE2, from the 
master catalog. Its parameters are: 

• SYS1.PAGE2, the entryname of the object to be deleted. SYS1.PAGE2 
identifies a page space entry. 

• PURGE, which specifies that the page space entry is to be deleted 
regardless of the retention period or date specified when it was defined. 

• PAGESPACE, which specifies the type of entry to be deleted. VSAM 
verifies that SYS1.PAGE2 is a page space entry, then deletes it. If 
SYS1.PAGE2 incorrectly identified another type of entry, VSAM would 
not delete it, but would send an error message to the programmer. 
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EXPORT Parameters 
Required Parameters 



EXPORT 



The format of the EXPORT command, when it is used to disconnect a user 
catalog, is: 



EXPORT 



usercatname {/password ] 
DISCONNECT 



The format of the EXPORT command, when it is used to move a cluster or 
alternate index, is: 



EXPORT 



entryname [/password ] 

[OUTFlLEidname) \ OUTDATASET(enrrvname)} 

[INFILE(rfmzme)] 

[ERASE I NOERASE] 

[INHIBITSOURCE | NOINHIBITSOURCE ] 

[INHIBITTARGET | NOINHIBITTARGET ] 

[PURGE I NOPURGE ] 

[TEMPORARY | PERMANENT] 



EXPORT may be abbreviated: EXP. 



entryname [/ password ] 

is a required parameter that names the cluster, alternate index, or user 
catalog to be exported. This parameter must be the first parameter 
following EXPORT. If you are exporting a user catalog, you must supply 
the update (or higher level) password of the master catalog. If you are 
exporting a cluster or alternate index, you must supply its (the object's) 
master password. If any password-protected paths are defined over the 
cluster or alternate index being exported, you must supply the master 
password of the catalog containing the objects in order to export the 
protection attributes of all the paths. 

DISCONNECT 

specifies that a user catalog is to be exported. The entry for the user 
catalog will be deleted from the master catalog. Also, the user catalog's 
alias entries are deleted from the master catalog. 

DISCONNECT is a required parameter if EXPORT is issued for a user 
catalog. The volume that contains the user catalog can be physically moved 
to the system to which the catalog will be imported. 

If DISCONNECT is coded, the entry name and the master catalog's 
update or higher-level password, and no other parameters, must be coded 
with it. To make a user catalog available in other systems and in the 
original system, code the IMPORT command to import the user catalog to 
each system to which it is to be available, but do not EXPORT the user 
catalog. 
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Optional Parameters 



Abbreviation: DCON 

OUTFILE( dname ) 

specifies the name of the DD statement that identifies the output data set 
to be created as a result of the EXPORT command. With the exception of 
blocksize, the data set characteristics of the output data set that is to 
contain the cluster to be exported should not be specified. The 
characteristics of the output data set are described in the section "Moving 
Entries." 

Blocksize is defaulted by the EXPORT command to 2048. Blocksize may 
be specified in the DD statement to override this default and improve 
performance. 

Abbreviation: OFILE 

OVTDATASETientryname 

specifies the name of the data set that is to receive the data being exported. 
If OUTDATASET is specified, the entryname is dynamically allocated. 
The characteristics of the output data set are described in the section 
"Moving Entries." 

Abbreviation: ODS 



ERASE I NOERASE 

specifies whether the data component of the cluster or alternate index to 
be exported is to be erased (that is, overwritten with binary zeros). This 
parameter overrides whatever was specified when the object was defined 
or last altered. This parameter can be specified only if the object is to be 
permanently exported (that is, deleted from the original system). 

Abbreviations: ERAS and NERAS 

INFILE( dname ) 

specifies the name of the DD statement that identifies the cluster or 
alternate index to be exported. If the cluster or alternate index has been 
defined with a maximum logical record length greater than 32,760 bytes, 
EXPORT processing terminates with an error message. 

In addition to the DD statement for INFILE, you must identify the entr/s 
catalog with a JOBCAT or STEPCAT DD statement unless: 

• The object's entry is in the master catalog, or 

• The first qualifier of the object's name identifies a catalog (that is, the 
first qualifier is the catalog's name or aUas). 

When INFILE and its DD statement aren't specified for a to-be-exported 
object, it is dynamically allocated. 

Abbreviation: IFILE 
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INHIBITSOURCE | NOINHIBITSOURCE 

specifies whether the original data records (that is, the data records of the 
source cluster or alternate index) can be accessed for any operation other 
than retrieval after its copy is exported. This specification can later be 
altered through the ALTER command. 

INHIBITSOURCE 

specifies that the source object in the original system cannot be accessed 
for any operation other than retrieval. This parameter can be specified 
only when the object is to be temporarily exported (that is, a backup 
copy of the object is made; the object itself remains in the original 
system). 

Abbreviatioii: INHS 

NOINHIBITSOURCE 

specifies that the source object in the original system can be accessed 
for any kind of operation. 

Abbreviation: NINHS 

INHIBirTARGET | NOINHIBITTARGET 

specifies whether the copy's records (that is, the target alternate index or 
cluster) can be accessed for any operation other than retrieval after it has 
been imported to another system. This specification can be altered through 
the ALTER command. 

INHIBirTARGET 

specifies that the target object cannot be accessed for any operation 
other than retrieval after it has been imported into another system. 

Abbreviation: INHT 

NOINHIBirrARGET 

specifies that the target object can be accessed for any type of operation 
after it has been imported into another system. 

Abbreviation: NINHT 

PURGE I NOPURGE 

specifies whether the cluster or alternate index to be exported is to be 
deleted from the original system regardless of the retention period, 
specified in a TO or FOR parameter when the object was defined. This 
parameter can be specified only if the object is to be permanently 
exported, that is, deleted from the original system. 

PURGE 

specifies that the object is to be deleted even if the retention period has 
not expired. 

Abbreviation: PRG 

NOPURGE 

specifies that the object is not to be deleted unless the retention period 
has expired. 

Abbreviation: NPRG 
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TEMPORARY | PERMANENT 

specifies whether the cluster or alternate index to be exported is to be 
deleted from the original system. 

TEMPORARY 

specifies that the cluster or alternate index is not to be deleted from the 
original system. The object in the original system is marked as 
temporary to indicate that another copy exists and that the original copy 
can be replaced. To replace the original copy, a portable copy created 
by an EXPORT command must be imported to the orijginal system. The 
IMPORT command deletes the original copy, defines the new object, 
and copies the data from the portable copy into the newly defined 
object. 

Abbreviation: TEMP 

PERMANENT 

specifies that the cluster or alternate index is to be deleted from the 
original system. Its storage space is freed. If its retention period has not 
yet expired, you must also code PURGE. 

Abbreviation: PERM 
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Exporting a Key-Sequenced Cluster: Example 1 

In this example, a key-sequenced cluster, D40.EXAMPLE.KSDS1, is 
exported from a user catalog, D27UCAT1. The cluster is copied to a portable 
fUe, TAPE2, and its catalog entries are modified to prevent the cluster's data 
records from being updated, added to, or erased. 

//EXPORT 1 JOB 
//STEP1 EXEC PGM=IDCAMS 

//RECEIVE DD DSNAME=TAPE2 ,UNIT=( 2400-3 ,, DEFER ) , 
// DISP=NEW,VOL=SER=003030, 

// DCB=( BLKSIZE=6000 , DEN=3 ) , LABEL=( 1 , SL) 

//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
EXPORT - 

D40. EXAMPLE. KSDS1 - 

OUTFILE( RECEIVE ) - 

TEMPORARY - 

INHIBITSOURCE 
/* 

The job control language statements are: 

• RECEIVE DD, which describes the portable file, a magnetic tape file, that 
is to receive a copy of the cluster's records. The DCB BLKSIZE parameter 
overrides the EXPORT default of 2048 to improve performance. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The EXPORT command copies the key-sequenced cluster, 
D40.EXAMPLE.KSDS1, to a portable fUe, TAPE2, and modifies the 
cluster's catalog entries (its cluster, data, and index entries). Access Method 
Services dynamically allocates D40.EXAMPLE.KSDS1, Since the high-level 
qualifier of the cluster name is the name of the alias of D27UCAT2, the 
cluster can be allocated without specifying a JOBCAT or STEPCAT DD 
statement. The EXPORT command's parameters are: 

• D40.EXAMPLE.KSDS1, which identifies the cluster to be exported. 
Because the cluster is not password protected, no password is provided 
with the cluster's entryname. 

. OUTFILE, which points to the RECEIVE DD statement. The RECEIVE 
DD statement describes the portable file, TAPE2, that is to contain a copy 
of the cluster. 

• TEMPORARY, which specifies that the cluster is not to be deleted. The 
cluster's catalog entry is marked "temporary" to indicate that another copy 
of the cluster exists and that the original copy can be replaced. (See the 
IMPORT Example 2, "Importing a Key-Sequenced Cluster.") 

• INHIBITSOURCE, which specifies the cluster (that is, the copy of it that 
remains in the original system, as a result of TEMPORARY) cannot be 
modified. User programs are allowed only to read the cluster's records. 
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Exporting an Entry-Sequenced Cluster: Example 2 



In this example, an entry-sequenced cluster is exported to a portable file and 
then it is deleted from the system. 

//EXP0RT2 JOB 
//STEP1 EXEC PGM=IDCAMS 

//RECEIVE DD DSNAME=TAPE1 , UNIT=( 2400-3 ,, DEFER ) , 
// VOL=SER=00 1147, LABEL=( 1 , SL) , DISP=NEW 
//SYSPRINT DD SySOUT=A 
//SYSIN DD * 
EXPORT - 

D50. EXAMPLE, ESDS1/DEPT26M - 

OUTFILE( RECEIVE), - 

PURGE 
/* 

The job control language statements are: 

• RECEIVE DD, which describes the portable file, TAPEl, that is to 
contain a copy of the exported entry-sequenced cluster. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The EXPORT command copies the entry-sequenced cluster, 
D50.EXAMPLE.ESDS1, to a portable file, TAPEl. The cluster is deleted 
from the system after it is copied into the portable file. Access Method 
Services dynamically allocates D50.EXAMPLE.ESDS1. Since the high-level 
quaUfier of the cluster is the name of the aUas of the catalog D27UCAT2, the 
cluster can be dynamically allocated without specifying a JOBCAT or 
STEPCAT DD statement. The EXPORT command's parameters are: 

• D50.EXAMPLE.ESDS1 , which identifies the entry-sequenced cluster to 
be exported, and which specifies the cluster's master password, DEPT26M. 
When a cluster is exported, its master password is required if it is password 
protected. 

• OUTFILE, which points to the RECEIVE DD statement. The RECEIVE 
DD statement describes the portable data set, TAPEl, that is to receive a 
copy of the cluster. 

s PURGE, which allows the cluster to be deleted regardless of its retention 
period or date. 

Because TEMPORARY is not specified. Access Method Services assumes the 
cluster is to be deleted once TAPEl contains a copy of it. 

Because INHIBITTARGET is not specified. Access Method Services assumes 
the cluster can be updated (by users of the other system) when it is imported 
to another system. 
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Exporting a User Catalog: Example 3 

In this example, the user catalog D27UCAT1 is exported — that is, it is 
disconnected from the system. Its cataloged objects are no longer available to 
users of the system. 

//EXPORTS JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
EXPORT - 

D27UCAT1/MRPWD27 - 

DISCONNECT 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The EXPORT command removes the user catalog connector entry for 
D27UCAT1 from the master catalog. The catalog becomes unavailable to 
system users until the system programmer reconnects it to the system, using 
an IMPORT CONNECT command. The EXPORT command's parameters 
are: 

• D27UCAT1, which identifies the object to be exported. When a user 
catalog is exported, the master catalog's master password is required. (See 
IMPORT Example 1, "Import a User Catalog.") 

• DISCONNECT, which identifies the exported object as a user catalog. 
When a user catalog is exported, DISCONNECT is required. 
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EXPORTRA 



EXPORTRA 



The format of the EXPORTRA command is: 



EXPORTRA Parameters 
Required Parameters 



EXPORTRA 



0\JT¥lh^{dmme) 
CRA( 

(dnamel 

{ALL[bINFILE(^nawe2 )] | 
ENTRIES( 

(entryname [hdnameS ]) 
[ientryname[h dnameS ])...]) I 
NONE}) 
[(dnamel ...)...]) 
[FORCE I NOFORCE ] 
[MASTERPW(pas5worJ )] 



EXPORTRA may be abbreviated: XPRA. 



OUTFILE( dname ) 

identifies the DD statement that describes the data set (usually a movable 
disk pack or magnetic tape reel) that is to contain a copy of the VSAM 
objects and catalog entries identified with the CRA parameter. With the 
exception of blocksize, the data set characteristics of the output data set 
that is to contain the cluster to be exported should not be specified. The 
characteristics of the output data set are described in the section "Copying 
a Catalog Entry from the Catalog Recovery Area." Blocksize is defaulted 
by the EXPORTRA command to 2048. Blocksize may be specified in the 
DD statement to override this default and improve performance. 

Abbreviation: OFILE 

CRA( 

( dnamel 

{ ALL [ b INFILE( dname2 ) ] | 
ENTRIES ( 

( entryname [ b dname3 ] ) 
[ ( entryname [ b dnameS ])...]) | 
NONE}) 
[ ( dnamel ... ) ... ] ) 

The CRA parameter and its subparameters describe the catalog recovery 
area to be referred to, identify the specific entries to be copied from the 
catalog recovery area, and specify the volumes that contain the entries' 
data. The subparameters are repeated to describe each catalog recovery 
area to be referred to, and whether its entries are to be copied. 
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dnamel 

identifies the DD statement that describes a volume whose catalog 
recovery area is to be referred to. Each dnamel you specify is followed 
by one of the following subparameters which specifies the action to be 
taken with regard to the catalog recovery area: 

ALL 

specifies that each entry in dnamel 's catalog recovery area is to be 
copied to the OUTFILE data set. In addition, the contents (that is, 
data records in logical sequential order) of each VSAM cluster and 
alternate index are copied, following the copy of the catalog recovery 
area entry. If any of these VSAM clusters or alternate indexes has 
data which resides on volumes other than that identified viia dnamel, 
you use INFILE to describe all the volumes. 

INFILE( dnamel ) 

identifies the DD statement that describes multiple volumes to be 
used in the recovery process. INFILE is required if the VSAM 
clusters and/ or alternate indexes whose entries are contained in 
dnamel 's catalog recovery area reside on multiple volumes, in 
addition to the dnamel DD statement, including the volume 
referenced by the dnamel DD statement. 

Abbreviation: IFILE 

ENTRIES ( 

( entryname [ fe dnameS ] ) 

[ ( entrynahte [ t> dnameS ])...]) 

names each" entry in the catalog recovery area that is to be copied to 

the OUTFILE data set. All other entries in the catalog recovery area 

are not copied. 

entryname 

names an object whose catalog entry is contained in the dnamel 
volume's catalog recovery area. You can specify the entryname of 
the following entry types: alternate index, cluster, and nonVSAM. 

When you specify a cluster entry, the cluster's data and index 
entries and all associated path entries are also copied. In addition, 
the cluster's contents (that is, its data records, in logical sequential 
order) are copied, following the copies of the cluster's catalog 
entries. 

When you specify an alternate index entry, the alternate index's 
entries and contents and all associated path entries are copied as 
though it were a key-sequenced cluster. 

dnameS 

identifies the DD statement that describes each volume that 
contains part of the cluster or alternate index. dnameS is ignored 
when specified for a nonVSAM entry. 

dnameS is required when the entry is a VSAM cluster or alternate 
index whose data resides on volumes other than the volume 
identified with the dnamel DD statement. The dnameS DD 
statement must also include the volume referenced by the dnamel 
DD statement. 

Abbreviation: ENT 
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NONE 

specifies that no object in the volume's catalog recovery area is to be 
recovered. You must specify dnamel NONE for each volume 
referenced in a dnamel or dnameS DD statement if you do not wish 
the entries in its catalog recovery area to be recovered. 



Optional Parameters 

FORCE I NOFORCE 



specifies whether the catalog entry's copy is to be copied from the catalog 
recovery area even though the copy itself might be inaccurate. 

When you specify FORCE, EXPORTRA ignores time stamp and extent 
mismatches and the object's catalog-entry copy is copied from the 
volume's catalog recovery area, even though a loss of data integrity might 
result. Otherwise, when the catalog recovery area's copy is not accurate, it 
is not copied and the EXPORTRA command terminates with an error 
message. 

Abbreviations: FRC and NFRC 

MASTERPW( password ) 

specifies the master catalog's master password. The master catalog's master 
password is required when the master catalog is password-protected. 

Abbreviation: MRPW 
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EXPORTRA Examples 

Using EXPORTRA for All Entries on One Volume: Example 1 



This example shows the EXPORTRA function for one volume, VO, owned by 
the VSAM master catalog. All of the entries contained in the catalog recovery 
area on VO and the data sets themselves are copied to a SAM data set on 
another disk volume. All of the data sets reside entirely within the one 
volume. 

//EXPORTRA JOB . . . 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 

//VLVO DD UNIT=3330,VOL=SER=V0,AMP='AMORG' ,DISP=OLD 
//VOLOUT DD UNIT=3330,VOL=SER=333003,DSN=OUT.FILE, 
// DISP=( NEW, KEEP ),SPACE=(CYL,( 5,1)), 

// DCB=BLKSIZE=6000 

//SYSIN DD * 
EXPORTRA - 

OUTF I LE( VOLOUT) - 
CRA ( - 
( VLVO ALL ) ) 
/* 

The job control language statements are: 

• VLVO DD, which identifies and allocates the volume whose catalog 
recovery area contents are to be copied. The data sets reside wholly within 
the one volume. 

• VOLOUT DD, which identifies the sequential file that is to receive the 
copied data sets and catalog recovery records. The DCB BLKSIZE 
parameter overrides the EXPORTRA default of 2048 to improve 
performance. 

The EXPORTRA command copies everything appearing in the catalog 
recovery area of volume VO. The EXPORTRA command parameters are: 

• ^OUTFILE, which is required and identifies the sequential (SAM) 

nonVSAM data set that is to receive the copied information. 

• CRA, which is required and identifies the catalog recovery area and 
volume from which the copy is to take place. VLVO identifies the DD 
statement for the catalog recovery volume. The ALL subparameter 
specifies that all entries are to be copied from the catalog recovery area. 
The INFILE subparameter is not required because the data sets are 
contained wholly within the one volume. 



Using EXPORTRA for All Entries on Multiple Volumes: Example 2 



This example shows the EXPORTRA function for one volume owned by the 
VSAM master catalog. All data sets contained on the volume, VO, and their 
corresponding CRA entries describing the data sets are copied to a sequential 
(SAM) data set on a tape volume. The catalog recovery area contains data 
sets which reside on volumes VI and V2 in addition to the recovery volume, 
VO. The entries in the catalog recovery areas of the additional volumes are 
not to be recovered. 
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//EXPORTRA JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 

//VLVO DD UNIT=3330,VOL=SER=V0,AMP='AMORG' , 
// DISP=OLD 

//VLV1 DD UNIT=3330,VOL=SER=V1 ,AMP='AMORG' , 
// DISP=OLD 

//VLV2 DD UNir=3330,VOL=SER=V2,AMP='AMORG' , 
// DISP=OLD 

//VOLA DD UNIT=( 3330,3 ),VOL=SER=(V0, VI ,V2 ), 
// AMP= • AMORG ' , DISP=OLD 

//VOLOUT DD DSN=OUT . FILE , LABEL=( 1 , SL) , 
// DISP=( NEW, KEEP), 

// UNIT=2400-3,VOL=SER=TAPE01 , 

// DCB=(BLKSIZE=8192,DEN=3 ) 

//SYSIN DD * 
EXPORTRA - 

OUTFILE( VOLOUT) - 
CRA ( - 

(VLVO ALL INFILE{VOLA) ) - 

(VLV1 NONE) - 

( VLV2 NONE ) ) - 
MASTERPW( MCATMRPW ) 
/* 

The job control language statements are: 

• VLVO DD, which identifies the volume whose catalog recovery area 
contents are to be exported. 

• ° VLVl and VLV2 DD, each of which identifies a volume containing part of 

a multivolume data set but whose catalog recovery area contents are not to 
be exported. 

• VOLA DD, which identifies all the volumes containing the data sets to be 
exported. 

• VOLOUT DD, which identifies the sequential tape file that is to receive 
the exported data sets and catalog recovery records. The DCB BLKSIZE 
parameter overrides the default of 2048 to improve performance. 

The EXPORTRA command copies every entry appearing in the catalog 
recovery area of volume VO and the data sets described by the CRA entries. 
Two additional volumes, VI and V2, are referenced since they contain part of 
multivolume data sets, but the entries in their catalog recovery areas are not 
exported. The EXPORTRA command parameters are: 

• OUTFILE, which is required and identifies the sequential (SAM) 
nonVSAM data set that is to receive the exported information. 

• CRA, which is required and identifies the catalog recovery area and 
volumes from which the copy is to take place. VLVO identifies the DD 
statement of the recovery volume. The ALL subparameter specifies that all 
entries in the catalog recovery area of the volume identified by VLVO are 
to be copied. The INFILE subparameter is required, since the data sets to 
be copied are contained on multiple volumes. VOLA references the DD 
statement which identifies these multiple volumes, including the recovery 
volume. The VLVl NONE and VLV2 NONE subparameters are necessary 
because the volumes they identify are referenced in a previous INFILE 
subparameter; however, the contents of their catalog recovery areas are 
not to be copied. 
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• MASTERPW, which specifies the master password of the master catalog. 
This parameter is required when the master catalog is password protected. 



Using EXPORTRA for Selected Entries: Example 3 



This example shows the EXPORTRA function for selected entries from the 
catalog recovery area of one volume owned by the VSAM master catalog. 
Three data sets and their corresponding entries from the catalog recovery area 
on volume VO are copied to a sequential (SAM) data set on another disk 
volume. The remainder of the data sets and the catalog recovery area entries 
are not copied. Two of the selected data sets are multivolume VSAM data 
sets. The data sets and their corresponding entries in the catalog recovery 
areas of the additional volumes are not recovered. 

//EXPORTRA JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 

//VLVO DD UNIT=3330,AMP='AMORG' ,DISP=OLD, 
// VOL=SER=V0 

//VLV1 DD UNIT=3330,AMP='AMORG' ,DISP=OLD, 
// V0L=SER=V1 

//VLV2 DD UNIT=3330,AMP='AMORG' ,DISP=OLD, 
// V0L=SER=V2 

//VOLA DD UNIT={ 3330,3 ),AMP='AM0RG' ,DISP=0LD, 
// VOL=SER=(V0,V1 ,V2) 

//VOLB DD UNIT=( 3330,2 ),AMP='AM0RG' ,DISP=0LD, 
// VOL=SER=(V0,V1 ) 

//VOLOUT DD UNIT=3330,VOL=SER=333003,DSN=OUT.FILE, 
// DISP=( NEW, KEEP ),SPACE=(CYL,( 5,1 ) ) 

//SYSIN DD * 
EXPORTRA - 

OUTFILE( VOLOUT) - 
CRA ( - 

(VLVO ENTRIES ( - 

( LARGE . DATASET . A VOLA) - 
( LARGE . DATASET . B VOLB) - 
( LARGE . DATASET . C) ) ) - 
(VLV1 NONE) - 
( VLV2 NONE ) ) - 
FORCE 
/* 

The job control language statements are: 

• VLVO DD, which identifies the volume whose catalog recovery area 
contains the entries for the three VSAM data sets to be copied. 

• VLVl and VLV2 DD, each of which identifies a volume containing part of 
a multivolume data set but whose catalog recovery area contents are not to 
be copied. 

• VOLA DD, which identifies the multivolumes of LARGE.DAT ASET.A 
. VOLB DD, which identifies the multivolumes of LARGE.DATASET.B 

• VOLOUT DD, which identifies the sequential file that is to receive the 
copied data sets and catalog recovery records. 
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The EXPORTRA command exports the three 
entries— LARGE.DATASET.A, LARGE.DATASET.B, and 
LARGE.DATASET.C — from the catalog recovery area on volume VO. Two 
additional volumes are referenced, since they contain part of multivolume 
data sets but the entries in their catalog recovery areas are not exported. The 
EXPORTRA command parameters are: 

• OUTFILE, which is required and identifies the nonVSAM data set that is 
to receive the exported information. 

• CRA, which is required and identifies the catalog recovery area and 
volumes from which the export is to take place. VLVO identifies the DD 
statement of the recovery volume. The ENTRIES subparameter identifies 
the three entries which are to be copied. LARGE.DATASET.A requires 
the VOLA subparameter because the VSAM data set is contained on three 
volumes. Similariy, LARGE.DATASET.B requires the VOLB 
subparameter. However, LARGE.DATASET.C is contained wholly within 
the catalog recovery volume, and, therefore, does not require an additional 
dnameS subparameter. The VLVl NONE and VLV2 NONE 
subparameters are necessary because the volumes they identify are 
referenced in previous dnameS subparameters (VOLA and VOLB); 
however, the contents of their catalog recovery areas are not to be copied. 

• FORCE, which specifies that timestamp mismatches are to be ignored. 
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IMPORT 



IMPORT 



IMPORT Parameters 

Required Parameters 



The format of the IMPORT command, when it is used to connect a user 
catalog, is: 



IMPORT 



CONNECT 
OBJECTS(( usercatname 

DEVICETYPEC devtype ) 

VOLUMES(vo/5er))) 
[CATALOG( mastercatname [/password ])] 



The format of the IMPORT command, when it is used to move or restore a 
cluster or alternate index, is: . 



IMPORT 



{mFllM{dname ) | INDATASET( enfryname )} 
{OMTFlUEidname [/password]) \ 

0\JYDPklXSET{entryname [/password])} 
[ERASE I NOERASE] 
[INTOEMPTY] 
[OB JECTS(( entryname 

[FILE( rfname)] 

[KEYRANGES(( lowkey b highkey ) 
[( lowkey b highkey )...])] 

[NEWNAMEC newname )] 

[ORDERED 1 UNORDERED] 

[VOLUMESC voher[h volser ...])]) 
[{entryname ,..)...])] 
[PURGE I NOPURGE ] 
[SAVRAC I NOSAVRAC ] 

[CATALOG( catname [/password ])] 



IMPORT may be abbreviated: IMP. 



CONNECT 

specifies that the entry to be imported is a user catalog. The user catalog is 
connected to the master catalog in the receiving system. If CONNECT is 
coded, OBJECTS must also be coded to name the catalog and to identify 
the volume serial number and device type of the volume that contains the 
user catalog. 

Abbreviation: CON 

INFILE( dname ) 

specifies the name of a DD statement that identifies the portable copy of 
the cluster or alternate index to be imported. If a non-labeled tape or a 
direct-access data set created by DOS/VS Access Method Services 
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contains the copy, the following DCB parameters must be specified on the 
referenced DD statement: 

• BLKSIZE. If you specified BLKSIZE when the cluster or alternate 
index was exported, you must specify the same blocksize value for 
IMPORT. (Note: If you did not specify a blocksize for EXPORT, a 
default value of 2048 was used. Consequently, if you do not specify 
BLKSIZE for IMPORT, IMPORT sets the blocksize to 2048.) 

• LRECL. LRECL is based on the maximum record size of the exported 
ySAM data set. Maximum record size is determined by the value 
specified via the maximum subparameter of the RECORDSIZE 
parameter of the DEFINE CLUSTER or DEFINE 
ALTERNATEINDEX command when the data set was defined. If the 
portable data set was created on a system with the OS/VS2 MVS 
Supervisor Performance #2 Selectable Unit VS2.03.807, LRECL is as 
follows: 

- For relative record data sets, the greater of 276, or VSAM maximum 
logical record size plus 8 

- For all other types of VSAM data sets, the greater of 272, or 
maximum VSAM logical record size plus 4 

• If the portable data set was created on any system without VS2.03.807, 

- For relative record data sets, the greater of 268, or VSAM logical 
record length plus 8 

- For all other types of VSAM data sets, the greater of 264, or 
maximum VSAM logical record length plus 4 

(Note: If you do not specify LRECL, IMPORT uses a default value of ( 

BLKSIZE -4.) 

. RECFM. Must be VBS. 

Abbreviation: IFILE 

INDATASETC entryname ) 

names the cluster or alternate index to be imported. 

If INDATASET is specified, the entryname is dynamically allocated. The 
entryname must be cataloged in a catalog that is accessible by the system 
into which the entry is to be imported. The characteristics of the input data 
set are described under the INFILE parameter. 

Abbreviation: IDS 

OUTFILE( dname [ / password ] ) 

specifies the name of a DD statement that identifies the data set name and 
volume(s) that is to receive the cluster or alternate index that is to be 
imported. If the data set was permanently exported and/or you are 
importing to a volume other than the original volume, the DD statement 
specifies the name of the cluster or alternate index as DSNAME, the 
volume serial number(s), the device type, DISP=OLD, and 
AMP='AMORG'. In addition, you must use concatenated DD statements 
when both of the following conditions exist and the data set was 
permanently exported: 

• An alternate index or key-sequenced cluster is being imported. 

• Its data and index components are on different device types. 



348 0S/VS2 Access Method Services 



IMPORT 

The first DD statement specifies the name of the cluster or alternate index 
as the DSNAME, the volume serial numbers and device type of the data 
component, DISP=OLD, and AMP='AMORG'. The second DD 
statement specifies the name of the index component as the DSNAME, the 
volume serial numbers and device type of its index component, 
DISP=OLD, and AMP='AMORG'. 

If NEWNAME is specified for the cluster or alternate index entry, the 
data-set name on the DD statement must be the same as the new name. 
The volume that is to receive the imported cluster or alternate index must 
be owned by a VSAM catalog. 

password 

is the update (or higher-level) password of the output cluster or 
alternate index. You must supply the password when the output data set 
is empty (see the VOLUMES parameter for more information about 
importing into an empty data set). Otherwise, IMPORT obtains the 
required VSAM data set passwords from the portable data set. 

When you use a DD statement to describe the output data set, you must 
identify the data set's catalog with a JOBCAT or STEPCAT DD statement 
unless: 

• The data set's entry is in the master catalog, or 

• The first qualifier of the data set's qualified name identifies a catalog 
(that is, the first qualifier is the catalog's name or alias). 

Abbreviation: OFILE 

OUTDATASET( entryname [ / password ] ) 

specifies the name of the data set that is to receive the data being 
imported. When you specify OUTDATASET, the VSAM data set you 
identify is dynamically allocated. If NEWNAME is specified for the cluster 
or alternate index entry, entryname must be the same as the new name. 

password 

is the update- (or higher-level) password of the output object. See 
password under INFILE for password requirements of the output data 
set. 

Abbreviation: ODS 
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Optional Parameters 



CATALOG( catname [/ password ]) 

specifies the name of the catalog in which the imported object is to be 
cataloged. This parameter is required when the catalog is password 
protected. 

catname 

is the name of the catalog in which the entry to be imported is to be 
defined. If you are importing a user catalog, the specified catalog must 
be the master catalog. 

password 

specifies the catalog's update or higher level password. When you 
import an alternate index whose base cluster is password-protected, you 
should supply the catalog's master password. Otherwise, you (or the 
operator) will be prompted to supply the base cluster's master password. 

Abbreviation: CAT 

ERASE I NOERASE 

specifies whether the data component of the cluster or alternate index that 
was exported with the TEMPORARY option is to be erased (that is, 
overwritten with binary zeros). This parameter can be used only when you 
are importing the object into the system from which it was previously 
exported with the TEMPORARY option. This parameter overrides 
whatever was specified when the object was defined or last altered. 

Abbreviations: ERAS and NERAS 

INTOEMPTY 

specifies that you are importing into an empty data set. If this parameter is 
not specified, an attempt to import into an empty data set will fail. 
Importing into an empty data set causes the data set to be loaded from the 
portable data set. The password and RACE profiles associated with the 
empty data set will be retained. When importing into an empty data set, the 
SAVRAC I NOSAVRAC parameter appUes only to the paths imported 
and successfully defined over the empty data set. If the define of an 
exported path fails because a catalog entry with the same name already 
exists, the path on the portable data set is ignored. 

Abbreviation: lEMPTY 

OBJECTS 

specifies the new or changed attributes for the cluster, alternate index, any 
associated paths, or user catalog to be imported. 

By specifying the OBJECTS parameter: 

• You provide the information needed to connect a user catalog to the 
master catalog, or 

• You may override certain attributes of the cluster or alternate index 
(and associated paths) to be imported in order to provide new or 
changed attributes. Access Method Services matches each entryname 
you specify through the OBJECTS parameter against the name of each 
object on the portable data set. When a match is found, the information 
specified by OBJECTS overrides the information on the portable data 
set. The description for each of the OBJECTS subparameter includes 
information on how they should be specified; that is, what name you 
should specify as the entryname to accomplish the results you want. 



350 0S/VS2 Access Method Services 



IMPORT 

You can specify OBJECTS 

• For a user catalog: 

OBJECTS(( usercatname 

DEMCETYPEC devtype ) 

VOLUMES( w&cr))) 

• For a cluster, alternate index, or path: 
OBJECTS( ( entrymme 

[FILE( dname)] 

[KEYRANGES(( lowkey b highkey ) 

[( lowkey b highkey )...])] 
[ NEWNAMEC newname ) ] 
[ORDERED I UNORDERED ] 
[ VOLUMESC vober [ b volser ...])]) 
[ ( entryname ... )...]) 

usercatname 

specifies the name of the user catalog being connected. 

entryname 

specifies the name of the data component, index component, cluster, 
alternate index, or path for which attributes are being specified. For a 
cluster, alternate index, data component, index component, or path, this 
name must appear on the portable data set; otherwise, the parameter list 
will be ignored. 

Abbreviation: OBJ 

DEVICETYPEC <kvt)^e ) 

specifies the device type of the volume that contains a user catalog that 
is to be connected. You can specify a device type for any direct-access 
device that is supported by your OS/VS2 MVS systems. 

Abbreviation: DEVT 

FILE( dname ) 

specifies the name of a DD statement that identifies the volumes 
allocated to the data and index components of a key-sequenced cluster 
or of an alternate index. This parameter is required when the 
components are defined as unique and when the data and index 
components reside on different device types. When components reside 
on different device types, FILE must be coded twice within the 
OBJECTS parameter: once in the parameter set for the index 
component and once in a second parameter set for the data component. 
If you do not specify FILE, the required volumes are dynamically 
allocated. 
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KEYRANGES(( lowkey b highkey ) [ ( lowkey b highkey )...]) 
specifies portions of a key-sequenced cluster or alternate index to be 
placed on separate volumes. 

The data is divided, by key, among the volumes as contained in the 
portable data set or as specified in the VOLUMES parameter. If a 
volume serial number is duplicated on the portable data set or in 
VOLUMES, multiple key ranges of an alternate index or cluster 
attribute are placed on that volume. If the number of volumes is greater 
than the number of key ranges, the excess volumes are used for 
overflow records from any key range without consideration of range 
boundaries. If there are fewer volumes than key ranges, the excess key 
ranges are placed on the last volume specified. 

By using the KEYRANGE parameter you may specify key range pairs 
for a key-sequenced data set that previously was not divided by key or 
that was divided in different key range groups. 

The maximum number of key-range pairs is 20. Key ranges must be in 
ascending order, and may not overlap. Gaps may exist within a specified 
set of ranges, but records cannot be inserted within a gap. 

When you specify KEYRANGES, entryname can be either the cluster 
or alternate index name or the name of the data component. If you 
specify KEYRANGES with the cluster or alternate index name, the 
values specified are propagated to and defined for the data component. 
If you specify KEYRANGES with the data component name the values 
are defined for the data component and any specification of 
KEYRANGES with the cluster or alternate index name is overridden. 

Keys can contain 1 to 64 characters; if coded in hexadecimal, they may 
contain 1 to 128 hexadecimal characters. All EBCDIC characters are 
allowed. Keys consisting of characters must be enclosed in single 
quotation marks if they contain commas, semicolons, blanks, 
parentheses, or slashes. A single quotation mark within a key must be 
coded as two single quotation marks if the key is enclosed in single 
quotation marks. If the key is specified in hexadecimal, it must be 
preceded by X and be enclosed in single quotation marks. 

lowkey 

specifies the low key of the key range. If lowkey is shorter than the 
actual keys, it will be padded with binary zeros. 

highkey 

specifies the high key of the key range. If highkey is shorter than the 
actual keys, it will be padded with binary ones. 

Abbreviation: KRNG 
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NEWNAMEC newname ) 

specifies the new name of an imported cluster or alternate index or its 
components, or an associated path. When you specify NEWNAME, 
only the name specified as entryname is changed. You cannot specify 
NEWNAME if entryname identifies a user catalog. 

The new name can contain 1 to 44 alphameric characters (A through Z, 
and through 9), national characters (@, #, and $), and special 
characters (the hyphen and 12-0 overpunch). Names that contain more 
than eight characters must be segmented by periods; one to eight 
characters may be specified between periods. The first character of the 
name or name segment must be either an alphabetic character or a 
national character. If you specify the new name in the format 
newname(modifier), only that portion of the name preceding the left 
parenthesis will be used. The modifier enclosed in parentheses will be 
ignored. 

If you are specifying a new name for a cluster or alternate index that 
was exported with the TEMPORARY option and it is being imported 
back into the original system, you must rename each of its components, 
also. 

Abbreviation: NEWNM 

ORDERED I UNORDERED 

specifies whether volumes are to be used in the order in which they were 
listed when the data set was originally defined (as contained on the 
portable data set) or in the VOLUMES parameter. If the data set is 
divided into key ranges, all of the records within the range specified by 
the first low-key/Mgh-key pair are placed on the first volume; all of the 
records within the second range are placed on the second volume; etc. If 
it is impossible to allocate volumes in the given order and ORDERED is 
specified, the command is terminated. 

When you specify ORDERED | UNORDERED, you can specify the 
cluster or alternate index name, the data component name or the index 
component name as entryname with the following results: 

. If ORDERED I UNORDERED is specified with the cluster or 
alternate index name, the specified attribute is propagated to and 
defined for the data and, for a key-sequenced cluster or alternate 
index, the index component. 

. If ORDERED I UNORDERED is specified with the data 
component name, the specified attribute is defined for the data 
component; Any specification of ORDERED | UNORDERED with 
the cluster or alternate index name is overridden. 

• For a key-sequenced cluster and for an alternate index, if 

ORDERED I UNORDERED is specified with tbe idex component 
name, the specified attribute is defined for the index component. Any 
specification of ORDERED | UNORDERED with the cluster or 
alternate index name is overridden. 

Abbreviations: ORD and UNORD 
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VOLUMES( wker [ b volser ... ] ) 

specifies the volumes on which the cluster or alternate index is to reside 
or the volume on which the user catalog resides. 

The volume serial number may contain one to six alphameric, national 
(@, #, and $), hyphens, and special (commas, semicolons, blanks, 
parentheses, slashes, asterisks, periods, quotation marks, ampersands, 
plus signs, and equal signs) characters. The volume serial numbers must 
be enclosed in single quotation marks if they contain special characters. 
Single quotation marks within a volume serial number must be coded as 
two single quotation marks. 

If VOLUMES is not coded, the original volume is the receiving volume. 
This parameter is required when a user catalog is to be imported; when 
importing a user catalog, specify only one volume. If the portable data 
set was created with an EXPORT command using the PERMANENT 
option on a Release 1 version of Access Method Services (DOS/VS 
Release 29, OS/VSl Release 2, OS/VS2 Release 1.6, or OS/VS2 
Release 2), this parameter is required. Portable data sets created by 
Release 1 using the PERMANENT option do not contain volume 
information. 

When you specify VOLUMES, you can specify the cluster or alternate 
index name, the data component name or the index component name as 
entryname with the following results: 

• If VOLUMES is specified with the cluster or alternate index name 
the specified volume list is propagated to and defined for the data 
and, for a key-sequenced cluster or alternate index, the index 
component. 

• If VOLUMES is specified with the data component name, the 
specified volume list is defined for the data component. Any 
specification of VOLUMES with the cluster or alternate index name 
is overridden. 

• For a key-sequenced cluster or alternate index, if VOLUMES is 
specified with the index component name, the specified volume list is 
defined for the index component. Any specification of VOLUMES 
with the cluster or alternate index name is overridden. 

For clusters or alternate indexes, multiple volumes, if specified, must be 
of the same device type. By repeating the OBJECTS parameter set for 
each component and including VOLUMES in each parameter set, you 
can have the data and index components on different volumes. Although 
the index and data components may reside on different device types, 
each volume of a multivolume component must be of the same type. 

If the receiving volume is of a type different from that that originally 
contained the cluster or alternate mdex, the job may be terminated 
because of allocation problems. Each space allocation quantity is 
recorded in a catalog entry as an amount of cylinders or tracks even 
when RECORDS was specified in the DEFINE command. When a 
cluster or alternate index is imported, the number of cylinders or tracks 
in the catalog entry is not modified, even though the object may be 
imported to reside on a device type other than that it was exported 
from. An attempt to import an object that previously resided on a 3330 
may fail if it is imported to a 2314. Conversely, if an object is exported 
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from a 2314 and imported to a 3330, more space is allocated than the 

I object needs. 

f 

You can avoid space allocation problems when you define an empty 
cluster or alternate index on the new system or catalog and identify it as 
the target for the object being imported as described below: 

• Using the DEFINE command, define a new entry for the cluster or 
alternate index in the catalog to which it is to be moved. If space was 
allocated in RECORDS, you may specify the same quantity; if it was 
allocated in TRACKS or CYLINDERS, you must adjust the quantity 
for the new device type. If an entry already exists in the catalog for 
the object, you must delete that entry or use a different name in the 
DEFINE conmiand. 

• Using the IMPORT command, load the portable data set into the 
newly defined cluster or alternate index. When IMPORT encounters 
an empty target data set, the exported catalog information is 
bypassed and just the data records are processed. 

Abbreviation: VOL 

PURGE I NQPURGE 

specifies whether the original cluster or alternate index is to be deleted and 
replaced regardless of the retention time specified in the TO or FOR 
parameter. This, parameter can be used only when you are importing the 
object into the original system from which it was exported with the 
TEMPORARY option. 

\ Abbreviations: PRO and NPRG 

SAVRAC I NOSAVRAC 

specifies, for a RACF-protected object, whether existing profiles are to be 
used or whether new profiles are to be created. 

SAVRAC should be specified when RACE data set profiles already exist 
for objects being imported from the portable data set. TypicaUy, you would 
specify this option when replacing a data set with a portable copy made 
with an EXPORT TEMPORARY operation. SAVRAC will cause the 
existing profiles to be "saved" and used, rather than letting the system 
delete old profUes and create new, default profiles. 

Caution: You should ensure that valid profiles do exist for all components 
(for example, cluster, data, index) being imported when SAVRAC is 
specified. If this is not done, an invalid and possibly improper profile may 
be "saved" and used inappropriately. Remember, that paths are imported 
along with their corresponding cluster or alternate index, and the same 
caution apphes to these entries. In particular, keep in mind that additional 
paths may be brought in during the import. 

NOSAVRAC should be specified when you wish new profiles to be 
created. This is usually the situation when importing a permanently 
. exported cluster or alternate index. A profile will be defined for the 
imported components if either the Automatic Data Set Protection option 
has been specified for you or if the exported component had a RACE 
indication in the catalog when it was exported. If you import into a catalog 
in which there is a component with a duplicate name which is marked as 
'I, having been temporarily exported, it and any associated profiles will be 

^ deleted before importing the portable data set. 
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IMPORT Examples 

Importii^ a User Catalog: Example 1 



In this example, a user catalog, D27UCAT1, is imported and connected to the 
new system's master catalog, AMASTCAT. This example reconnects the user 
catalog, D27UCAT1, that was disconnected with EXPORT Example 3. 

//IMPORT 1 JOB . . . 
//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

IMPORT - 

OBJECTS ( - 

{D27UCAT1 - 
VOLUME (VSERO 2) - 
DEVICETYPE( 2314) ) - 
) - 
CONNECT - 

CATALOG ( AMASTCAT/MRCATPW2 ) 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The IMPORT command buUds a user catalog connector entry that identifies 
the user catalog D27UCAT1 in the master catalog AMASTCAT. Its 
parameters are: 

• OBJECTS, which is required when a user catalog is being imported. The 
subparameters of OBJECTS identify the user catalog, D27UCAT1, the 
user catalog's volume, VSER02, and the device type of the user catalog's 
volume, 2314. 

• CONNECT, which specifies that the user catalog connector entry is to be 
built and put in the master catalog to connect the user catalog to the 
master catalog. CONNECT is required when a user catalog is being 
imported. 

• CATALOG, which identifies the master catalog, AMASTCAT, and 
specifies its update- (or higher-level) password, MRCATPW2. 
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Importing a Key-Sequenced Cluster: Example 2 

In this example a key-sequenced cluster, D40.EXAMPLE,KSDS1, that was 
previously exported, is imported. (See the previous EXPORT example, 
"Exporting a Key-Sequenced Cluster.") OUTFILE and its associated DD 
statement are provided to allocate the data set. 

The original copy of D40.EXAMPLE.KSDS1 is replaced with the imported 
copy, TAPE2. Access Method Services finds and deletes the duplicate name, 
D40.EXAMPLE.KSDS1, in the catalog D27UCAT1. (A duplicate name 
exists because TEMPORARY was specified when the cluster was exported.) 
Access Method Services then redefines D40.EXAMPLE.KSDS1 using the 
catalog information from the portable file, TAPE2. 

//IMP0RT2 JOB 

//STEP! EXEC PGM=IDCAMS 

//SOURCE DD DSNAME=TAPE2,UNIT=( 2400-3,, DEFER), 

// VOL=SER=003030,DISP=OLD, 

// DCB={BLKSIZE=6000,LRECL=479,DEN=3 ),LABEL=( 1 , SL) 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 
IMPORT - 

INF I LE( SOURCE) - 

OUTDATASET( D40. EXAMPLE. KSDS 1 ) - 

CATALOG! D27UCAT1/MRPWD27 ) 

/* 

The job control language statements are: 

• SOURCE DD, which describes the portable data set, TAPE2. TAPE2 
resides on a magnetic tape file, which will not be mounted by the operator 
until Access Method Services opens TAPE2 for processing. The blocksize 
parameter is included (even though it need not be, because the tape has a 
standard label and the information is contained in the data-set header 
label) to illustrate the fact that the information specified when the data set 
is imported is required to be the same as was specified when the data set 
was exported. The LRECL parameter is not required, because the 
maximum record size is 475 bytes and the default (blocksize minus 4) is 
adequate. However, by specifying a recordsize, the default is overridden 
and virtual storage is more efficiently used. When recordsize is specified, it 
is the largest-record size + 4. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The IMPORT command copies the portable data set, TAPE2, into the system 
and assigns it the name D40.EXAMPLE.KSDS1. When TAPE2 is copied, 
Access Method Services reorganizes the data records so that deleted records 
are removed and control intervals and control areas contain the specified 
f reespace percentages. The original copy of the cluster is deleted and replaced 
with the data records from the TAPE2 portable file. The IMPORT 
command's parameters are: 

• INFILE, which points to the SOURCE DD statement. The SOURCE DD 
statement describes the portable file, TAPE2, to be imported. 

• OUTDATASET, which gives the name of the data set being imported. 
Since the high-level qualifier of the data set is the name of the alias of the 
user catalog D27UCAT2, Access Method Services can dynamically 
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aUocate the cluster without specifying a JOBCAT or STEPCAT DD 
statement. 

CATALOG, which identifies the catalog, D27UCAT1, in which the 
imported cluster is to be defined. The catalog's update- (or higher-level) 
password is required. 



Importing an Entry-Sequenced VSAM Cluster: Example 3 



In this example, an entry-sequenced cluster, DSO.EXAMPLE.ESDSl, is 
imported from a portable file, TAPEl. This example is associated with 
EXPORT Example 2, "Exporting an Entry-Sequenced Cluster." The cluster 
is defined in a different catalog from which it was exported, assigned a new 
name, and imported to a different volume. 

//IMPORTS JOB ... 
//STEP1 EXEC PGM=IDCAMS 

//SOURCE DD DSNAME=TAPE1 ,UNIT=( 2400-3, , DEFER ),DISP=OLD 
// VOL=SER=00 1147, LABEL=( 1 , SL) 

//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

IMPORT - 

INFILE( SOURCE ) - 

OUTDATASET( D40. EXAMPLE. ESDS3 ) - 

OBJECTS ( - 

(DSO.EXAMPLE.ESDSl - 

NEWNAME( D40. EXAMPLE. ESDS 3 ) - 
VOLUMES(VSER02 ) ) - 
) - 
CATALOG( D27UCAT1/UPPWD27 ) 
/* 

The job control language statements are: 

e SOURCE DD, which describes the portable fUe, TAPEl. TAPEl resides 
on a magnetic tape file, which wUl not be mounted by the operator until 
Access Method Services opens TAPEl for processing. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The IMPORT command moves the contents of the portable file, TAPEl, into 
the system. When TAPEl is moved, Access Method Services reorganizes the 
data records. The IMPORT command's parameters are: 

• INFILE, which points to the SOURCE DD statement. The SOURCE DD 
statement describes the data set to be imported, TAPEl. 

• OUTDATASET gives the name of the data set that is being imported — the 
name is the renamed cluster. Since the high-level qualifier of the data set 
name is the name of the alias of the catalog, D27UCAT1, the data set can 
be dynamically allocated without specifying a JOBCAT or STEPCAT DD 
statement. 

• OBJECTS, which changes some of the attributes for the object being 
imported: 

- DSO.EXAMPLE.ESDSl, which identifies the entry-sequenced cluster as 
it is currently named on TAPEl. 

- NEWNAME, which specifies that the cluster's entryname is to be 
changed to D40.EXAMPLE.ESDS3. 
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- VOLUMES, which identifies the new volume on which the cluster is to 
reside. 

CATALOG, which identifies the catalog, D27UCAT1, that is to contain 
the cluster's catalog entry. The catalog's update- (or higher-level) password 
is required. 
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This parameter can be specified only when the entryname names a 
I nonVSAM data set or user catalog. For a nonVSAM data set or user 

catalog, if DEVICETYPES is not coded, the data set or user catalog 
must still reside on the same device type(s) as contained in the entry 
in the portable data set. 

Abbreviation: DEVT 

FILE( dname ) 

specifies the name of a DD statement that identifies the volumes 
allocated to the data and index components of a key-sequenced 
cluster or of an alternate index. This parameter is required when the 
components are defined as unique and when the data and index 
components reside on different device types. When components 
reside on different device types, FILE must be coded twice within the 
OBJECTS parameter; once in the parameter set for the index 
component and once in a second parameter set for the data 
component. If you do not specify FILE, the required volumes are 
dynamically allocated. 

VOLUMESC volser [ b vober ... ] ) 

specifies the volume(s) on which a cluster or alternate index is to 
reside, the volume on which a user catalog resides, or the volume(s) 
on which a nonVSAM data set resides. If entryname names a user 
catalog, you may specify only one volume serial number as a 
subparameter of VOLUMES. 

For a cluster or alternate index, if VOLUMES is not coded, the 
\ original volume is the receiving volume. For a user catalog or 

nonVSAM data set, if VOLUMES is not coded, the data set or user 
catalog must still reside on the same volume (s) as contained in the 
portable data set. 

voker 

is a 1 to 6 alphameric or national character volume serial number. 

When the volser contains a special character (that is, a comma [,], 
semicolon [;], blank [ b ], period [.], single quote ['], ampersand 
[ & ], plus sign [+], equal sign [=], hyphen [-], parenthesis [( or )], 
slash [/], or asterisk [*]), enclose the volser in single-quotation 
marks (for example, VOLUMESC *DORIS')). 

When the volser contains a special character and also contains a 
single-quotation mark, code the imbedded quotation mark as two 
single-quotation marks (for example, VOLUMESC*CA"RO')). 

You can code volser in hexadecimal form, where two hexadecimal 
characters represent one EBCDIC character. For example, 
VOLUMES(X'E2E4C5') is the same as VOLUMES(SUE). 

When you specify VOLUMES for a cluster or alternate index, you 
can specify the cluster or alternate index name, the data 
component name or the index component name as entryname with 
the following results: 

• If VOLUMES is specified with the cluster or alternate index 
name, the specified volume list is propagated to and defined for 
\ the data and, for a key-sequenced cluster or alternate index, the 

/ index component. 

Command Format 363 



• If VOLUMES is specified with the data component name, the 
specified volume list is defined for the data component. Any 
specification of VOLUMES with the cluster or alternate index 
name is overridden. 

• For a key-sequenced cluster or alternate index, if VOLUMES is 
specified with the index component name, the specified volume list 
is defined for the index component. Any specification of 
VOLUMES with the cluster or alternate index name is overridden. 

For cluster or alternate indexes, if multiple volumes are specified, 
they must be of the same device type. By repeating the OBJECTS 
parameter set for each component and including VOLUMES in each 
parameter set, you can have the data and index components on 
different volumes. (See also the description of the FILE parameter.) 
Although the index and data components may reside on different 
device types, each volume of a multivolume component must be of 
the same type. 

Abbreviation: VOL 

OIJTFILE( dname ) 

names the DD statement that contains a data set name and the volume 
serial number of each volume that is to contain the imported VSAM 
clusters and alternate indexes. You must use concatenated DD statements 
if the data sets are on different device types. If the OUTFILE parameter is 
not supplied, the required data sets are dynamically allocated as needed. 

The dsname specified with the DD statement cannot be one of the names 
cataloged in the target catalog (that is, the catalog that is to contain the 
imported catalog entries) and it cannot be one of the entrynames within 
the portable data set. The section "Restoring the Catalog Entry that was 
Obtained Using the EXPORTRA Command" describes how this dsname is 
used by IMPORTRA processing. The DD statement(s) also specify the 
volume serial number(s), device type, DISP=OLD, and AMP='AMORG'. 

Abbreviation: OFILE 

SAVRAC I NOSAVRAC 

specifies, for a RACF-protected object, whether existing profiles are to be 
used or whether new profiles are to be created. 

SAVRAC should be specified when RACE data set profiles already exist 
for objects being imported from the portable data set. SAVRAC wiU cause 
the existing profUes to be "saved" and used, rather than letting the system 
delete old profiles and create new default profiles. 

Caution: You should ensure that valid profiles do exist for all components 
(for example, cluster, data, index) being unported when SAVRAC is 
specified. If this is not done, an invalid and possibly improper profile may 
be "saved" and used inappropriately. Remember, that paths are imported 
along with their corresponding cluster or alternate index, and the same 
caution applies to these entries. In particular, keep in mind that additional 
paths may be brought in during the import. 

NOSAVRAC should be specified when you wish new profiles to be 
created. A profile will be defined for the imported components if either the 
RACE Automatic Data Set Protection option has been specified for you or 
if the exported component had a RACE indication in the catalog at the 
time it was exported. The mode, SAVRAC or NOSAVRAC, set by these 
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keywords applies to all VSAM components being imported back into the 
system. 

There may be situations where the SAVRAC or NOSAVRAC mode would 
not be suitable for all entities restored from the catalog recovery area. In 
such cases, the following procedure is suggested: 

• Issue two separate EXPORTRA commands, resulting in two portable 
data sets. One EXPORTRA will create a portable data set containing 
entities to which SAVRAC should apply, the other to which 
NOSAVRAC should apply. 

• Issue two IMPORTRA commands, one specifying SAVRAC and the 
other NOSAVRAC. 
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IMPORTR4 Example 



This example shows how EXPORTRA and IMPORTRA can be used to 
recover a VSAM catalog. The fkst part illustrates the use of EXPORTRA. 
The second part shows how IMPORTRA is used. 



Recovering a VSAM Catalog: Example 1 — Part 1 (EXPORTRA) 



This example performs the EXPORTRA function against the VSAM master 
catalog, AMASTCAT, and against all of the volumes owned by it. All of the 
data sets listed in the catalog recovery areas on the catalog volume and on the 
other volumes owned by AMASTCAT are exported to a SAM data set on 
another disk volume. Using the FORCE option causes EXPORTRA to ignore 
time stamp mismatches between the volumes and the catalog. 

//RECOVER JOB 

//STEP1' EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//CRAV0L1 DD DISP=OLD,VOL=SER=VSER01 ,UNIT=2314, 

// AMP= • AMORG ' 

//CRAV0L2 DD DISP=OLD, VOL=SER=VSER04 ,UNIT=3330 , 

// AMP= ' AMORG ' 

//PORT DD DSNAME=PORT , DISP=( NEW , KEEP ) , 

// SPACE=(CYL,(3,3) ),VOL=SER=231401 , 

// UNIT=2314,DCB=BLKSIZE=8000 

//SYSIN DD * 

EXPORTRA - 
CRA( - 

(CRAV0L1 ALL) - 
(CRAV0L2 ALL) - 
) - 
FORCE - 

OUTFILE(PORT) - 
MASTERPW( MCATiyiRPW ) 
/* 

The job control language statements are: 

• CRAVOLl DD, which identifies and allocates the first volume whose 
catalog recovery area contents is to be exported. 

• CRAVOL2 DD, which identifies and allocates the second volume whose 
catalog recovery area contents is to be exported. 

• PORT DD, which identifies the sequential file that is to receive the 
exported data sets and catalog recovery records. The DCB BLKSIZE 
parameter overrides the EXPORTRA default of 2048 to improve 
performance. 

The EXPORTRA command exports everything appearing in the catalog 
recovery areas of volumes VSEROl and VSER04. The EXPORTRA 
command's parameters are: 

• CRA, which is required and identifies the catalog recovery areas and 
volumes from which the export is to take place. The dnames of the DD 
statements for these objects must be identical to the names specified for 
this parameter. The ALL subparameter specifies that everything is to be 
exported from each catalog recovery area. 

• FORCE, which specifies that timestamp mismatches are to be ignored. 

• OUTFILE, which is required and identifies the sequential (SAM) 
nonVSAM data set that is to receive the exported information. The dname 
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of the DD statement for this object must be identical to the name specified 
with this parameter. 

MASTERPW, which specifies the master password of the master catalog. 
This parameter is required in order to export information from catalog 
recovery areas controlled by a recoverable catalog. 



Recovering a VSAM Catalog: Example 1— Part 2 (IMPORTRA) 



This example imports all of the data sets that were exported using 
EXPORTRA in the previous example. The receiving catalog is the VSAM 
master catalog, and the CATALOG parameter is used to supply its master 
password. 

//RESTORE JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD . SySOUT=A 

//PORT DD DSNAME=PORT,DISP=OLD,UNIT=2314, 

// VOL=SER=231401 ,DCB=BLKSIZE=8000 

//VSAMIN DD DSNAME=DUMMY.NAME,DISP=OLD,UNIT=2314, 

// VOL=SER=VSER0 1 , AMP= ' AMORG ' 

// DD VOL=SER=VSER04,UNIT=3330,DISP=OLD 

//SYSIN DD * 

IMPORTRA - 

INFILE(PORT) - 
OUTF I LE( VSAMIN) - 
CATALOG ( AMASTCAT/MCATMRPW ) 
/* 

The job control language statements are: 

• PORT DD, which identifies and allocates the portable data set created 
previously by EXPORTRA. The DCB BLKSIZE parameter is mcluded 
(even though it need not be because the information is contained in the 
DSCB for the data set) to illustrate the fact that the blocksize specified in 
the IMPORTRA job must be the same as that specified in the 
EXPORTRA job which created the portable data set. 

• VSAMIN DD, which identifies and allocates the volumes of the objects to 
be imported. This permits them to be reloaded from the portable data set. 
The dsname appearing on the DD statement is required. It is a dummy 
name that must not appear either in the catalog or among the names on the 
portable data set. Because the volumes are of different device types, 
concatenated DD statements must be used. 

The IMPORTRA command imports the data sets written on the portable data 
set by EXPORTRA previously. The IMPORTRA command's parameters are: 

• INFILE, which is required and which identifies the portable data set. 

• OUTFILE, which identifies each VSAM volume involved in the import. 
The DD statement identified by OUTFILE also identifies the dummy data 
set, DUMMY.NAME. 

• CATALOG, which specifies the name of the master catalog. The master 
password of the target catalog is required in order to import catalog 
information. 
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LISTCAT Parameters 

Required Parameters 



The format of the LISTCAT command is: 



LISTCAT 



[CATALOG( catname {/password ])] 
{l£KTV(SES{entryname {/password ] 

[b entryname {/password]...]) \ 

hEVEUhvel)] 
[ALL^S] 

[ b ALTERNATEINDEX] 

[bCLUSTER] 

[bDATA] 

[ b GENERATIOND ATAGROUP] 

[b INDEX] 

[bNONVSAM] 

[bPAGESPACE] 

[bPATH] 

[b SPACE] 

[bUSERCATALOG] 
[ALL! 

ALLOCATION | 

HISTORY I 

NAME I 

VOLUME] 
[CREATION(fiqy5)] 
[EXPIRATIONCJaF^)] 
[NOTUSABLE] 
[OUTFILEC^/wme)] 



LISTCAT may be abbreviated: LISTC. 



The LISTCAT command has no required parameters. 

The LISTCAT command is issued as a job step (that is, not through TSO) 
and no parameters are specified; an entire catalog is listed. See the section 
"Order of Catalog User: LISTCAT" for a description of how the catalog to 
be Usted is selected. 

Note to TSO users: When LISTCAT is invoked from a TSO terminal and no 
operands are specified, the prefix of the TSO user becomes the highest level 
of entryname quaUfication and only those entries with a matching highest 
level of qualification are listed. It is as if you specified: 
LISTCAT LEVEL( TSO -user-prefix ) 



Optional Parameters 






[ALLiS] [b ALTERNATEINDEX][bCLUSTER] [bDATA] 
[bGENERATIONDATAGROUP] [bINDEX] [bNONVSAM] 
[bPAGESPACE] [bPATH] [bSPACE] [bUSERCATALOG] 

specifies that certain types of entries are to be listed. Only those entries 
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whose t3rpe is specified is listed (that is, when you specify CLUSTER but 
not DATA or INDEX, the cluster's entry is listed and its associated data 
and index entries are not listed). When you identify an entry with its name 
(that is, when you specify ENTRIES) and also specify an entry type, the 
names entry is not listed unless it is of the specified type. You can specify 
as many entry types as desired. When you want to completely list a catalog, 
do not specify any entry type. 

ALIAS 

specifies that alias entries are to be listed. 

ALTERNATEINDEX 

specifies that entries for alternate indexes are listed. If 
ALTERNATEINDEX is specified and DATA and INDEX are not also 
specified, entries for the alternate-index's data and index components 
aren't listed. 

Abbreviation: AIX 

CLUSTER 

specifies that cluster entries are to be listed. If CLUSTER is specified 
and DATA and INDEX are not also specified, entries for the cluster's 
data and index components are not listed. 

Abbreviation: CL 

DATA 

specifies that entries for data components of clusters and alternate 
indexes, are to be listed. If a VSAM object's name is specified and 
DATA is coded, only the object's data-component entry is listed. When 
DATA is the only entrytype parameter coded, the catalog's data 
component is not listed. 

GENERATIONDATAGROUP 

specifies that entries for generation data groups are to be listed. 

Abbreviation: GDG 

INDEX 

specifies that entries for index components of key-sequenced clusters 
and alternate indexes are to be listed. If a VSAM object's name is 
specified and INDEX is coded, only the object's index-component entry 
is listed. When INDEX is the only entrytype parameter coded, the 
catalog's index component is not listed. 

Abbreviation: IX 

NONVSAM 

specifies that entries for nonVSAM data sets are to be listed. If a 
generation data group's name and nonVSAM are specified, the 
generation data sets associated with the generation data group are Usted. 

Abbreviation: NVSAM 

PAGESPACE 

specifies that, entries for page spaces are to be listed. 

Abbreviation: PGSPC 

PATH 

specifies that entries for paths are listed. 
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SPACE 

specifies that entries for volumes containing data spaces defined in this 
catalog are to be listed. Candidate volumes are included. If entries are 
identified by entryname, SPACE can be coded only when no other 
entrytype parameter is coded. 

Abbreviation: SPC 

USERCATALOG 

specifies that catalog connectors are to be listed. The user-catalog 
connector entries are in the master catalog. (User-catalog connector 
entries can also be in a user catalog, but the OS/VS2 system does not 
recognize them when searching for a user catalog.) 

Abbreviation: UCAT 

ALL I ALLOCATION | fflSTORY | NAME | VOLUME 

specifies the fields to be included for each entry listed. "Appendix B: 
Interpreting LISTCAT Output Listings" shows the listed information that 
results when you specify nothing (which defaults to NAME), ALL, 
VOLUME, ALLOCATION, and HISTORY. 

ALL 

specifies that all fields are to be listed. 

ALLOCATION 

specifies that the information provided by specifying VOLUME and 
detailed information about the allocation are to be listed. The 
information about allocation is listed only for data and index component 
entries. 

Abbreviation: ALLOC 

HISTORY 

specifies that only the following information is to be listed for each 
entry: name, entry type, ownerid, creation date, expiration date, and for 
a recoverable catalog's entries, the catalog recovery area's volume, 
device type, and control interval number. It can be specified for 
CLUSTER, DATA, INDEX, ALTERNATEINDEX, PATH, 
GENERATIONDATAGROUP, PAGESPACE, and NONVSAM. 

Abbreviation: HIST 

NAME 

specifies that the name and entry type of the entries are to be listed. 

Note to TSO users: Only the name of each entry associated with the 
TSO user's prefix is listed when no other parameters are coded. 

Some entry types are listed along with their associated entries. The 
entrytype and name of the associated entry follows the Usted entry's 
name. For details, see "ASN: Associations Group" in "Appendix B: 
Interpreting LISTCAT Output Listings." 

VOLUME 

specifies that the information provided by specifying HISTORY, and the 
volume serial numbers and device types allocated to the entries are to be 
listed. Volume information is only Usted for data and index component 
entries, data-space (volume) entries, nonVSAM data-set entries, and 
user-catalog connector entries. 
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Note to TSG users: Only the name and volume serial numbers 
associated with the TSO user's prefix are listed when no other 
parameters are coded. 

Abbreviatioii: VOL 

CATALOG( catname [/ password ] ) 

specifies the name of the catalog that contains the entries that are to be 
listed. If CATALOG is coded, only entries from that catalog are listed. See 
"Order of Catalog Use: LISTCAT" for information about the order in 
which catalogs are searched. 

catname 

is the name of the catalog. 

password 

specifies the read-level or higher-level password of the catalog that 
contains entries to be listed. If the entries to be listed are password 
protected, a password must be supplied either through this parameter or 
through the ENTRIES parameter. If passwords are to be listed, you 
must specify the master password. 

If the catalog's volume is physically mounted, it is dynamically allocated. 
The volume must be mounted as permanently resident or reserved. 

Abbreviation: CAT 

CREATION( days ) 

specifies that entries of the indicated type (CLUSTER, DATA, etc.) are to 
be listed only if they were created the specified number of days ago or 
earlier. 

days 

specifies the number of days ago. This value can be expressed in 
decimal, hexadecimal, or binary. If it is expressed in hexadecimal or 
binary, it must be preceded by X or B and be enclosed in single 
quotation marks. The maximum number that can be specified is 9999; 
zero indicates that all entries are to be listed. 

Abbreviation: CHEAT 

E>rrRIES( entryname [/ password ][ b entryname [ / password ]...]) | 
LEVEL( level ) 

specifies the names of entries to be Usted. The entire catalog is listed when 

aO of the following are true: 

- ENTRIES, LEVEL, NOTUSABLE, CREATION, and EXPIRATION 
are not coded. 

- No entrytype parameter is coded. 

- TSO is not being used to issue the LISTCAT command. 

Entries are only listed from an OS CVOL if the ENTRIES or LEVELS 
parameter is specified and: 

- The CATALOG parameter is not specified 

- No JOB or STEPCAT DD is specified 

- The higher level qualifier of the name specified using ENTRIES or 
LEVELS is the alias of a CVOL 
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ENTRIES( entryname [ / password ] 

[ b entryname [ / password ]...]) 

specifies the name or generic name of each entry to be listed. When you 
want to list the entries that describe a user catalog, the catalog's volume 
must be physically mounted. You then specify the catalog's name as the 
entryname. If you want data space information, you must specify the 
volume serial number (as the entryname) of the volume containing the 
data space; you must also specify SPACE and no other entrytype 
parameters. 

If the ENTRIES parameter specifies a generic name, a maximum of 
1456 entries can be listed. 

Note to TSO users: When you specify an incomplete qualified 
entryname, TSO prompts you to complete it. 

password 

specifies a password when the entry to be listed is password protected 
and a password is not specified with the CATALOG parameter. The 
password must be any of the entry's passwords. The entry's 
protection attributes are listed only when you specify the entry's (or 
its catalog's) master password. When you don't supply a password for 
a password-protected entry, the operator or TSO terminal user is 
prompted for the entry's password. You cannot supply a password for 
these types of entries: nonVSAM data set, generation data group, 
alias, user-catalog connector, and data space. 

Abbreviation: ENT 

LEVEL( level ) 

specifies that all entries that match the level of qualification specified by 
( level ) are to be listed irrespective of the number of qualifications after 
the level. If a generic level name is specified, one qualifier replaces 
the*. 

Note: The * may not specify the last level of qualifications. 

As an example, suppose the VSAM catalog contains the following 
names: 

1. A.A.B 

2. A.B.B 

3. A.B.B.C 

4. A.B.B.C.C 

5. A.C.C 

6. A.D 

7. A.E 

If ENTRIES(A.*) is specified, then entries 6 and 7 would be listed. If 
ENTRIES(A.*.B) is specified, then entries 1 and 2 would be listed. If 
LEVEL(A,*.B) is specified, then entries 1,2,3 and 4 would be Usted. If 
LEVEL(A) is specified, then entries 1,2,3,4,5,6 and 7 would be listed. 

If the LEVEL parameter is specified, a maximimi of 1456 entries can be 



^ listed. 
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Note to TSO users: TSO will prefix the userid to the specified data-set 
name when the ENTRIES parameter is specified with an unqualified 
entry name. The userid is not prefixed when the LEVEL parameter is 
specified. 

Abbreviation: LVL 

EXPIRATION( days ) 

specifies that entries of the indicated type (CLUSTER, DATA, etc.) are to 
be Usted only if they will expire the specified number of days from now or 
earUer. 

days 

specifies the number of days from now. This value can be expressed in 
decimal, hexadecimal, or binary. If it is expressed in hexadecimal or 
binary, it must be preceded by X or B and be enclosed in single 
quotation marks. The maximum number that can be specified is 9999 
and it indicates that all entries are to be listed. Any value that exceeds 
the year 2000 wiU default to 99.999(yyddd). Zero indicates that only 
entries that have already expired are to be Usted. 

Abbreviation: EXPIR 

NOTUSABLE 

specifies that only those data and index entries which have the "unusable" 
indicator on are to be listed. A data or index component is marked 
"unusable" when a system failure occurs that results in damage to the 
entry's cataloged information. 

When the cataloged information is reset, the damaged entry and its backup 
copy (in the catalog recovery area) might not match when the space 
allocation information is compared. VSAM marks the catalog entry 
"unusable" until the space allocation information is corrected. See 
"Restoring Catalog Entries After System Failure" for more details. 

Abbreviation: NUS 

OlJTFILE( dname ) 

specifies a data set, other than the SYSPRINT data set, to receive the 
output produced by LISTCAT (that is, the listed catalog entries). 
Completion messages produced by Access Method Services are sent, along 
with your job's JCL and input statements, to the SYSPRINT data set. 

dname identifies a DD statement that describes the alternate output data 
set. If OUTFILE is not specified, the entries are Usted in the SYSPRINT 
data set. If an alternate data set is specified, it must meet the requirements 
shown under "Output Data Sets" in the "Introduction." 

Abbreviation: OFILE 
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LISTCA T Examples 

Listing a Key-Sequenced Cluster's Entry: Example 1 

In this example, a key-sequenced cluster entry is listed. 

//LISTCAT1 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SySOUT=A 
//SYSIN DD * 
LISTCAT - 

ENTRIES! D40. EXAMPLE. KSDS 1 ) - 

CLUSTER - 

ALL 
/* 

The job control language statements are: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. The 
LISTCAT output wiU also be sent to the SYSPRINT output device. 

The LISTCAT command Usts the cluster's catalog entry. It is assumed that 
the high level of the qualified cluster name is the same as the alias of the 
catalog D27UCAT1; this naming convention directs the catalog search to the 
appropriate catalog. Its parameters are: 

• ENTRIES, which identifies the entry to be listed. 

• CLUSTER, which specifies that only the cluster entry is to be listed. If 
CLUSTER had not been specified, the cluster's data and index entries 
would also be listed. 

• ALL, which specifies that all fields of the cluster entry are to be listed. 

Alter a Catalog Entry, Then List the Modified Entry: Example 2 

In this example, the freespace attributes for the data component (KSDATA) 
of cluster MYDATA are modified. Next, the cluster entry, data entry, and 
index entry of MYDATA are listed to determine the effect, if any, the 
modification has on the cluster's other attributes and specifications. 

//LISTCAT2 JOB 

//JOBCAT DD DSNAME=D27UCAT1 ,DISP=SHR 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
ALTER - 

KSDATA - 
FREESPACE ( 10 10) 
IF LASTCC = - 
THEN - 
LISTCAT - 

ENTRIES (MYDATA) - 
ALL 
/* 

The job control language statements are: 

• JOBCAT DD, which makes a catalog available for this job: D27UCAT1. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
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COMPARE i NOCQMPARE 

specifies whether the list is to be limited to those entries in the catalog 
recovery area which do not match their corresponding catalog entries. 

When you specify COMPARE, only those entries which do not match are 
listed. All of the catalog's entries are compared, except the catalog's 
self-describing records. You must identify the catalog (that contains the 
to-be-compared catalog entries) with the CATALOG parameter. 

When you specify NOCOMPARE (or allow it to default), all of the catalog 
recovery area's records are Usted. 

The COMPARE parameter cannot be specified if you specify 
SEQUENTIALDUMP. 

Note: If you specify the COMPARE option, page space entries will always 
result in a mismatch. This is a normal condition and does not require any 
corrective action. The mismatch is due to the OPEN indicator not being set 
in the page space record in the CRA, whereas it is set in the catalog. 

See "Appendix D: Interpreting LISTCRA Output Listings" for examples 
of each type of output listing. 

Abbreviations: CMPR and NCMPR 

DUMP 1 NAME I SEQUENTIALDUMP 

specifies the amount of cataloged information to be listed. 

DUMP 

specifies that each listed entry is printed in its entirety in both 
hexadecimal and character form, sorted alphamerically and grouped. 

NAME 

specifies that each listed entry includes only the entry's name, its volume 
serial numbers, and the name and entry type of each associated entry. 
All listed entries are sorted alphamerically and grouped. 

SEQUENTIALDUMP 

specifies that each listed entry is to be printed in its entirety in both 
hexadecimal and character form. Records are listed in the sequence each 
appears in the catalog recovery area. 

The DUMP, NAME, SEQUENTIALDUMP, COMPARE, and 
NOCOMPARE options can be specified to produce five different kinds of 
output listing. See "Appendix D: Interpreting LISTCRA Output Listings" 
for examples of each type of hsting. 

MASTERPW( password ) 

specifies the master catalog's master password. You must supply the master 
catalog's master password with the MASTERPW parameter when the 
master catalog is password-protected. 

Abbreviation: MRPW 

OUTnLE( dname ) 

identifies the DD statement that describes an alternate output data set. See 
"Output Data Sets" for more details about alternate output data sets. 
When OUTFILE is not specified, the listing is printed on the output device 
described with the SYSPRINT DD statement. When OUTFILE is 
specified, the listing produced by LISTCRA is sent to the alternate output 
data set; the remainder of the Access Method Services output is printed on 
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LISTCRA 

the^ output device described with the SYSPRINT DD statement. Refer to 
"Appendix D: Interpreting LISTCRA Output Listings" for an example of 
the use of the OUTFILE parameter. 

Abbreviation: OFILE 



USTCRA Example 

Listing a Catalog Recovery Area: Example 1 



This example Usts the catalog recovery areas for those volumes owned by the 
VSAM master catalog, AMASTCAT, in dump format, and compares those 
catalog recovery areas with the actual catalog records themselves. 

//LISTAREA JOB 
//STEP! EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 

//CRAV0L1 DD DISP=OLD,VOL=SER=SG2001 ,UNIT=2314 
//CRAV0L2 DD DISP=OLD, VOL=SER=VSER04 ,UNIT=3330 
//GATVOL DD DSNAME=AMASTCAT,DISP=OLD 
//SYSIN DD * 
LISTCRA - 

INFILE( - 
CRAV0L1 - 
CRAV0L2 ) - 

MASTERPW( MCATMRPW ) - 

COMPARE - 

DUMP - 

CATALOG! AMASTCAT/MCATMRPW CATVOL ) 
/* 

The job control language statements are: 

• CRAVOLl DD, which identifies and allocates the volume that contains 
the first catalog recovery area to be listed. 

• CRAVOL2 DD, which identifies and allocates the volume that contains 
the second catalog recovery area to be listed. 

• CATVOL DD, which identifies and allocates the catalog to be compared 
against, and makes the catalog available to LISTCRA as a data set. 
Because this example is listing the master catalog, no STEPCAT or 
JOBCAT DD statement is required. However, if the example were listing a 
user catalog, a STEPCAT or JOBCAT DD statement would be required in 
addition to the CATVOL DD statement to describe the user catalog as a 
catalog. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. The listing 
produced by LISTCRA is also sent to this same output device. 

The LISTCRA command causes the catalog recovery areas on volumes 
SG2001 and VSER04 to be listed and their contents compared vdth the 
VSAM system catalog AMASTCAT. The LISTCRA command's parameters 
are: 

• INFILE, which is required and specifies the catalog recovery areas to be 
listed by identifying the DD statement that describes each CRA's volume. 



Command Format 379 



MASTERPW, which specifies the master password of the master catalog. 
This parameter is required in order to open the catalog recovery areas for 
LISTCRA processing. 

COMPARE, which specifies that the catalog records are to be compared 
with their copies in the catalog recovery areas. 

DUMP, which specifies that the results of the record comparison (that is, 
the LISTCRA output listing) is to be printed in dump format. 

CATALOG, which is required (because the COMPARE option was 
specified) and identifies the catalog to be compared against by identifying 
the DD statement that describes and allocates the catalog as a data set. 
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PRINT 



PRINT 



The format of the PRINT command is: 



PRINT 



{INFILE( dmme [/password ]) | 

JNDATASETientryname [/password])} 
[OVTFILEidname)] 
[CHARACTER | PUMP 1 HEX] 
[FROMKEYCJtej ) | ¥ROMADDttESS( address ) 

FROMNUMBERC nwmZjer) | SKlPicomt)] 
[TOKEY( key ) | TOADDRESS( address ) | 

TONlJMBERinumber) \ COUNT(com«0] 



PRINT Parameters 
Required Parameters 



INFILEC dname [/ password ]) | 
INDATASET( entryname [ / password ] ) 

identifies the data set or component to be printed. 

INFILEC dname [ / password ] ) 

specifies the name of the DD statement that identifies the data set or 
component. You can list a base cluster in alternate-key sequence by 
specifying a path name as the data set name in the DD statement. See 
the section "Printing Data Sets" for information on DCB parameters 
required for nonVSAM data sets. 

Abbreviation: IFELE 

INDATASET( entryname [ / password ] ) 

specifies the name of the entry to be printed. If INDATASET is 
specified, the entryname is dynamically allocated. You can list a base 
cluster in alternate-key sequence by specifying a path name as 
entryname. 

password 

If a VSAM data set or component is password protected, a password 
must be supplied. The password to be supplied is the master password of 
the catalog if you are Usting a catalog, or the read- or higher-level 
password of the data set or component if the data set or component is 
not a catalog. You can specify the master password of the cluster if you 
are listing a component of a password-protected cluster. Passwords are 
applicable only to VSAM data sets and their components. 

Abbreviation: IDS 



\ 
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Optional Parameters 



CHARACTER | DUMP | HEX 

specifies the format of the listing. 

CHARACTER 

specifies that each byte in the logical record is to be printed as a 
character. Bit patterns not defining a character are printed as periods. 
Key fields are listed in character format (see Figure 10). 

Abbreviation: CHAR 

DUMP 

specifies that each byte in the logical record is to be printed in both 
hexadecimal and character format. In the character portion of the 
listing, bit patterns not defining a character are printed as periods. Key 
fields are listed in hexadecimal format (see Figure 11). 

HEX 

specifies that each byte in the logical record is to be printed as two 
hexadecimal digits. Key fields are listed in hexadecimal format (see 
Figure 12). 



TIME: 19:26:13 



03/08/75 PAGE 6 



IDCAMS SYSTEM SERVICES 

LISTING OF DATA SET -EXAMPLE .LXSTC .DATA 

RBA OF RECORD - 

ABCD0OO0000000O1ABCDEFGH1JKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012345 
6789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXY20123456789ABCDEFGH 
IJKLMNOPQRSTUVWXYZ0123456789ABCDEFGH1JKLMN0PQRSTUVWZYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRST 
UVWXYZ0123456789ABCDEFGHIJKLMNOPQRST 



Figure 10. Character Format 



IDCAMS SYSTEM SERVICES 
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LISTING OF DATA SET -EXAMPLE. LISTC 



KEY OF 


RECORD - 


FOFOPOFOFi 


0000 


C1C2C3C4 


FOFOFOFO 


0020 


D8D9E2E3 


E4E5E6E7 


0040 


n4D5D6D7 


D8D9E2E3 


0060 


C9D1D2D3 


D4D5D6D7 


0080 


C5C6C7C8 


C9D1D2D3 


OOAO 


C1C2C3C4 


C5C6C7C8 


OOCO 


F6F7F8F9 


C1C2C3C4 


OOEO 


F2F3F4F5 


F6F7F8F9 ' 


0100 


E8E9F0F1 


F2F3F4F5 


0120 


E4E5E6E7 


E8E9F0F1 


0140 


D8D9E2E3 


E4E5E6E7 


0160 


D4D5D6D7 


D8D9E2E3 


0180 


C9D1D2D3 


D4D5D6D7 



OFOFOFOF0F0FOF1 
FOFOFOFO F0F0F0F1 
E8E9F0F1 F2F3F4F6 
E4E5ESE7 FCF9F0F1 
D8D9E2E3 E4E5E6E7 
D4D5D6D7 D8D9E2E3 
C9D1D2D3 D4D5D6D7 
C5C6C7C8 C9D1D2D3 
C1C2C3C4 C5C6C7C8 
F6F7F8F9 C1C2C3C4 
F2F3F4F5 F6F7F8F9 
E8E9F0F1 P2F3F4F5 
E4E5E6E7 E8E9F0F1 
D8D9E2E3 00000000 



C1C2C3C4 C5C6C7C8 C9D1D2D3 D4D5D6D7 *ABCD000000000001ABCDEFGHIJKLMNOP* 

F6F7F8F9 C1C2C3C4 C5C6C7C8 C9D1D2D3 «QRSTUVWXYZ0123456789ABCDEFGHIJKL* 

F2F3F4F5 F6F'7f8Fy C1C2CJC4 C5C6C7C8 *MNOPQRSTUVWXYZ01 23456789ABCDEFGH' 

E8E9F0F1 F2F3F4F5 F6F7F8F9 C1C2C3C4 •IJKLMNOPQRSTUVWXYZ0123456789ABCD* 

E4E5E6E7 E8E9F0F1 F2F3F4F5 F6F7F8F9 *EFGHIJKLMNOPQRSTUVWXYZ0 12 3456789* 

D8D9E2E3 E4E5E6E7 E8E9F0F1 F2F3F4F5 •ABCDEFGHIJKLMNOPQRSTUVWXYZ01 2345* 

D4D5D6D7 D8D9E2E3 E4E5E6E7 E8E9F0F1 *6789ABCDEFGHIJKLMNOPQRSTUVWXYZ01 * 

C9D1D2D3 D4D5D6D7 D8D9E2E3 E4E5E6E7 •23456789ABCDEFGHIJKLMNOPQRSTUVWX* 

C5C6C7C8 C9D1D2D3 D4D5D6D7 D8D9E2E3 •YZ0123456789ABCDEFGHIJKLMNOPQRST* 

C1C2C3C4 C5C6C7C8 C9D1D2D3 D4D5D6D7 •UVWXYZ0123456789ABCDEFGHIJKLMNOP* 

P6F7F8F9 C1C2C3C4 C5C6C7C8 C9D1D2D3 *QRSTUVWXYZ01 23456789ABCDEFGHIJKL* 

F2F3F4F5 F6F7F8F9 C1C2C3C4 C5C6C7C8 *MNOPQRSTUVWXYZ01 23a56789ABCDEFGH* 

♦IJKLMNOPQRST • 



Figure 1 1 . Dump Format 
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IDCAMS SYSTEM SERVICES 

LISTING OF DATA SET -EXAMPLE .LISTC. DATA 

RBA OF RECORD - 

C1C2C3C4F0F0FOF0F0FOFOF0F0F0FOF1C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9FOP1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8 

C9D1D2D3D4D5D6D7D8D9E2D3D4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9F0F1F2F3F4F5 

F6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3 

E4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8 

C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9F0F1F2F3F4F5 

F6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9F-F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3 

E4E5E6E7E8E9F0F1F2F3F4F5f6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E300000000 



Figure 12. Hex Format 
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PRINT 

FROMKEYC key ) | FROMADDRESS( address ) | 

FROMNUMBER( number ) | SKIP( count ) 

specifies the location in the data set being listed from which Usting is to 
start. If no value is specified, the listing begins with the first logical record 
in the data set or component. The only value that can be specified for a 
SAM data set is SKIP. 

FROMKEY( key ) 

specifies the key of the first record you want listed. You can specify 
generic keys — ^that is, keys shorter than that defined for the data set. If 
you specify generic keys, listing begins at the first record whose key 
matches that portion of the key you specified. (You cannot specify a 
key longer than that defined for the data set. If you do, the listing is not 
performed.) If the specified key is not found, the next higher key is used 
as the starting point for the listing. 

FROMKEY can be specified only when an alternate index, a 
key-sequenced VSAM data set, a VSAM catalog, or an 
indexed-sequential (ISAM) nonVSAM data set is being printed. When 
you specify FROMKEY, you cannot also specify TO ADDRESS to 
identify the last record to be printed. 

key can contain 1 to 255 EBCDIC characters, key must be enclosed in 
single quotation marks if it contains commas, semicolons, blanks, 
parentheses, or slashes. A single quotation mark within a key must be 
coded as two single quotation marks. You can code key in hexadecimal 
form where the hexadecimal value is enclosed in single quotation marks 
and preceded by an X — for example, X'C2C1C8'. key can contain up 
to 255 hexadecimal characters. 

Abbremtion: FKEY 

FROMADDRESS( address ) 

specifies the relative byte address (RBA) of the first record you want 
listed. The RBA value must be the beginning of a logical record. If you 
specify this parameter for a key-sequenced data set, the listing will be in 
physical sequential order instead of in logical sequential order. 
FROMADDRESS can be specified only for VSAM key-sequenced or 
entry-sequenced data sets or components. FROMADDRESS cannot be 
specified when the data set is accessed through a path. 
FROMADDRESS cannot be specified for a key-sequenced data set with 
spanned records if any of those spanned records are to be accessed. 

Abbremtion: FADDR 

FROMNUMBER( number ) 

specifies the relative-record number of the first record you want printed. 

Abbreviation: FNUM 

SKIP( count ) 

specifies the number of logical records you want to skip before the 
listing of records begins. For example, if you want the listing to begin 
with record number 500, you specify SKIP(499). SKIP should not be 
specified when you are accessing the data set through a path; the results 
are unpredictable. 
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address, number, and count can be expressed in decimal (n), hexadecimal 
(X*n'), or binary (B'n'); the expression cannot be longer than one fuUword 
(eight decimal or hexadecimal numbers, or 32 binary numbers). 

OUTFILE( dname ) 

identifies an alternate output data set — that is, an output data set other 
than SYSPRINT. For dname substitute the name of the JCL statement 
that identifies the alternate output data set. The standard Access Method 
Services output data set for listings, which is identified by the DD name 
SYSPRINT, is the default. The output data set must meet the requirements 
stated in the "Introduction" under "Output Data Sets." 

Abbreviation: OFILE 

TOKEY( key ) | TOADDRESS( address ) | 

TONUMBERC number ) | COUNT( count ) 

specifies the location in the data set being listed at which listing is to stop. 
If no value is specified, the listing ends with the logical end of the data set 
or component. The only value that can be specified for a sequential data 
set is COUNT. The location at which the listing is to stop must follow the 
location at which the listing is to begin. 

The ending delimiter must be consistent with the starting delimiter. For 
example, if FROMADDRESS is specified for the starting location, neither 
TOKEY nor TONUMBER may be specified for the location. Similarly, if 
FROMNUMBER is specified for the starting location, neither TOKEY nor 
TOADDRESS may be specified for the ending location. 

TOKEY( key ) 

specifies the key of the last record to be listed. You can specify generic 
keys — that is, keys shorter than that defined for the data set. If you 
specify generic keys, listing stops after the last record is listed whose key 
matches that portion of the key you specified. (You cannot specify a 
key longer than that defined for the data set. If you do, the listing is not 
performed.) If the specified key is not found, the next lower key is used 
as the stopping point for the listing. 

TOKEY can be specified only when an alternate index, a key-sequenced 
VSAM data set, a VSAM catalog, or an indexed-sequential (ISAM) 
nonVSAM data set is being printed. 

key can contain 1 to 255 EBCDIC characters, key must be enclosed in 
single quotation marks if it contains commas, semicolons, blanks, 
parentheses, or slashes. A single quotation mark within a key must be 
coded as two single quotation marks. You can code key in hexadecimal 
form where the hexadecimal value is enclosed in single-quotation marks 
and preceded by an X — for example, X'C2C1C8'. key can contain up 
to 255 hexadecimal characters. 

TOADDRESS( address ) 

specifies the relative byte address (RBA) of the last record you want 
listed. Unlike FROMADDRESS, the RBA value does not need to be the 
beginning of a logical record. The entire record containing the specified 
RBA is printed. If you specify this parameter for a key-sequenced data 
set, the Usting will be in physical sequential order instead of in logical 
sequential order. TOADDRESS can be specified only for VSAM 
key-sequenced or entry-sequenced data sets or components. 
TOADDRESS cannot be specified when the data set is accessed through 
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a path. TO ADDRESS cannot be specified for a key-sequenced data set 
with spanned records if any of those spanned records are to be accessed. 

Abbreviation: TADDR 

TONUMBERC number ) 

specifies the relative-record number of the last record you want printed. 

Abbreviation: TNUM 

COUNT( count ) 

specifies the number of logical records to be Usted. COUNT should not 
be specified when you are accessing the data set through a path; the 
results are unpredictable. 

address, number, and count can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n'); the expression cannot be longer than one fullword 
(eight decimal or hexadecimal numbers, or 32 binary numbers). 
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PRINT Examples 

Print a Key-Sequenced Cluster's Data Records: Example 1 



In this example, the data records of a key-sequenced cluster, 
D40.EXAMPLE.KSDS1, are printed in dump format. That is, each character 
of the record is printed in its hexadecimal and alphameric forms, 

//PRINT 1 JOB . . . 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
PRINT - 

INDATASET( D40. EXAMPLE. KSDS1 ) 
/* 

The job control language statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. The listing 
produced by PRINT is sent to the same output device. 

The PRINT command prints data records of the key-sequenced cluster, 
D40.EXAMPLE.KSDS1. Its parameter is: 

• INDATASET, which names the data set to be printed. Since the data set is 
cataloged in D27UCAT1 and the high-level qualifier of the data set is the 
name of the ahas of D27UCAT1, Access Method Services can dynamically 
allocate the cluster without the need of JOBCAT or STEPCAT DD 
statements. 

Because neither FROMADDRESS, FROMKEY, SKIP, TOKEY, 
TOADDRESS, or COUNT is specified, Access Method Services assumes that 
all of the cluster's data records are to be printed. 

Because neither HEX nor CHAR was specified, Access Method Services 
prints each record in the DUMP format. An example of the printed record is 
shown in Figure 13. 



KEY OF RECORD - 00F0FOFOF0F1C9E24OC4C1405CC6C9 

0000 OOFOFOFO F0F1C9E2 40C4CiaO 5CC6C9D3 C540C9F0 C6F8F05C 40F5F040 D9C5C3D6 *. 00001 IS DA *FILE I0D80» 50 RECO* 

0020 D9C4E240 D6C640F6 F940C3C8 C1D9E240 E6C9E3C8 40D2C5E8 40C9D540 D7D6E240 *RDS OF 69 CHARS WITH KEY IN POS * 

0040 F160F1F1 4BOOO0OO 00000000 00000000 *1-11 



Figure 13. An Example of the Printed Record in DUMP Format 
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Copy Records From a NonVSAM Data Set Into an Entry-Sequenced VSAM 
Cluster, Then Print the Records: Example 2 



J 



In this example, the first fifteen records from a nonVSAM data set, 
EXAMPLE.NONVSAM, are copied into an entry-sequenced cluster, 
D50.EXAMPLE.ESDS1. If the records were copied correctly, the cluster's 
records are printed in hexadecimal format. Finally, even if the records were 
not copied correctly, the nonVSAM data set's first fifteen records are printed 
in character format. 

//PRINT2 JOB . . . 

//JOBCAT DD DSNAME=D27UCAT1 ,DISP=SHR 
// DD DSNAME=D27UCAT2,DISP=SHR 

//STEP1 EXEC PGM=IDCAMS 

//VSDSET2 DD DSNAME=D50 .EXAMPLE. ESDS1 ,DISP=OLD 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
REPRO - 

INDATASET( EXAMPLE . NONVSAM ) - 

OUTFILE(VSDSET2/DEPT27U) - 

COUNT! 15) 

IF LASTCC = - 
THEN - 
PRINT - 

INFILE(VSDSET2) - 

HEX 



PRINT - 

INDATASETC EXAMPLE . NONVSAM ) - 

COUNT( 15) - 

CHARACTER 

N /* 



The job control language statements are: 

• JOBCAT DD, which makes two catalogs available for this job: 
D27UCAT1 and D27UCAT2. Concatenated JOBCAT DD statements 
were used to identify both catalogs. 

• VSDSET2 DD, which identifies the entry-sequenced VSAM cluster, 
D50.EXAMPLE.ESDS1, that the records are copied into. 

Note: If the AMP=(BUFND=n) parameter was specified, performance 
would improve when the data set's records are accessed. BUFND was 
allowed to default in this example, because only 15 records are being 
processed. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. The Usting 
produced by the PRINT commands is sent to the same output device. 

The REPRO command copies the first fifteen records from the input data set, 
EXAMPLE.NONVSAM, into the output entry-sequenced cluster, 
D50.EXAMPLE.ESDS1. Its parameters are: 

• INDATASET, which identifies the input data set, 
EXAMPLE.NONVSAM. Because a JOBCAT DD statement is included 
with the job, VSAM will search for the catalog entry describing the 
nonVSAM data set in either D27UCAT1 or D27UCAT2 user catalog, or 
in the master catalog. 
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. OUTFILE, which pomts to the VSDSET2 DD statement. The VSDSET2 
DD statement identifies the output data set, D50.EXAMPLE.ESDS1. 
VSAM assumes that D50.EXAMPLE.ESDS1 is cataloged either in 
D27UCAT1 or D27UCAT2 user catalog, or in the master catalog. 

• COUNT, which specifies that fifteen records are to be copied. Because the 
SKIP parameter was not specified, Access Method Services assumes that 
the first fifteen records are to be copied. FROMNUMBER, 
FROMADDRESS, and FROMKEY cannot be specified for a nonVSAM 
data set. The records are always added after the last record in the output 
data set. 

The IF ... THEN command sequence verifies that the REPRO command 
completed successfully before the first PRINT command executes. 

The first PRINT command prints the records in the entry-sequenced cluster, 
D50.EXAMPLE.ESDS1. Its parameters are: 

. INFILE, which points to the VSDSET2 DD statement. The VSDSET2 DD 
statement identifies the cluster, D50.EXAMPLE.ESDS1. VSAM assumes 
that the cluster is cataloged either in D27UCAT1 or D27UCAT2 user 
catalog, or in the master catalog. 

• HEX, which specifies that each record is to be printed as a group of 
hexadecimal characters. An example of the printed record is shown in 
Figure 14. 

Note: The IF ... THEN command sequence ends with the HEX parameter, 
because no continuation character f oUows this parameter. If you want two or 
more Access Method Services commands to execute only when the IF 
statement is satisfied, enclose the commands in a DO... END command 
sequence. 

The second PRINT command, which executes even if the REPRO command 
failed, prints the first fifteen records of the nonVSAM data set, . 
EXAMPLE.NONVSAM. Its parameters are: 

• INDATASET, which identifies the nonVSAM data set 
EXAMPLE.NONVSAM. VSAM will search for the catalog entry in either 
D27UCAT1 or D27UCAT2 user catalog or in the master catalog. 

• COUNT, which specifies that fifteen records are to be printed. Because 
SKIP was not specified. Access Method Services assumes that the first 
fifteen records are to be printed. FROMNUMBER, FROMADDRESS, or 
FROMKEY cannot be specified for a nonVSAM sequential data set. 

• CHARACTER, which specifies that each record is to be printed as a group 
of alphameric characters. An example of the printed record is shown in 
Figure 15. 



RBA OF RECORD - 

C2D6E8C5D94040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040a040404040 

4040404040404040404040404040404040404040 



Figure 14. An Example of the Printed Record in Hexadecimal 
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RECORD SEQUENCE NUMBER 
CLARK 



Figure 15. An Example of a Printed Alphameric Character Record 



Print A VSAM Catalog: Example 3 



This example shows various ways to print a VSAM catalog. You may find this 
function of the PRINT conmiand helpful in the event of a problem with your 
catalog. 

//PRINTS JOB . . . 

//JOBCAT DD DSNAME=D27UCAT1 ,DISP=OLD 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SYS IN DD * 

/* PRINT THE LOW KEY RANGE OF THE CATALOG */ 
PRINT - 

INDATASET(D27UCAT1 ) - 
TOKEY (X'3F' ) 

/* PRINT THE HIGH KEY RANGE OF THE CATALOG */ 
PRINT - 

INDATASET(D27UCAT1 ) - 
FROMKEY (X'40' ) 

/* PRINT A SPECIFIC RECORD */ 
/* FROM THE LOW KEY RANGE */ 
PRINT - 

INDATASET(D27UCAT1 ) - 

FROMKEY (X'OOOOOOOE' ) - 

COUNT ( 1 ) 

/* PRINT THE ENTIRE CATALOG */ 
PRINT - 

INDATASET(D27UCAT1 ) 
/* 

The job control language statements are: 

• JOBCAT DD, which is required and which describes and allocates the user 
catalog to be printed. 

• SYSPRINT DD, which is required in aU Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. The listings 
produced by the PRINT commands are sent to the same output device. 

The first PRINT command prints the low-keyrange of the catalog. Its 
parameters are: 

• INDATASET, which specifies the name of the catalog to be printed. 

• TOKEY, which specifies that printing is to terminate after reaching a 
record whose key is greater than X'3F' (in its first byte). The low-keyrange 
of a VSAM catalog contains records with a range of keys having a value 
from X'OO' to X'3F' in the first byte. 
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The second PRINT command prints the high-kejn-ange of the catalog. Its 
parameters are: 

• INDATASET, which specifies the name of the catalog to be printed. 

• FROMKEY, which specifies that printing is to begin at the first record 
whose key is X'40' or greater (in its first bjrte). The high-keyrange of a 
VSAM catalog contains records with a range of keys having a value from 
X'40' to X'FF' in the first byte. 

The third PRINT command prints one catalog record from the low-keyrange 
of the catalog. Its parameters are: 

• INDATASET, which specifies the name of the catalog to be printed. 

• FROMKEY, which specifies that printing is to begin with the record whose 
key is X' OOOOOOOE' in the first four bytes. Records in the low-keyrange of 
a VSAM catalog have the number of the containing control interval as the 
first four bytes of their key. Records are 505 bytes in length and each 
record is contained in a 512-byte control interval. 

• COUNT, which specifies that only one record is to be printed. 

The fourth PRINT command prints the entire catalog, because there are no 
delimiting parameters specified. 
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REPRO 



The format of the REPRO command is: 



REPRO 



{INFILE( dname [/password ] 

[bENVIRONMENT(DUMMY)]) | 
INDATASET( entryname [/password ] 
[ bENVIRONMENT(DUMMY)])} 
{OUTFILE( dname [/password ]) | 

OUlDkThSWlientryname [/password])} 
[REPLACE I NOREPLACE ] 
[REUSE I NOREUSE ] 
[FROMKEY(feeK) | FROMADDRESS(fl^t/res5) | 

FROMNUMBERC Rum^r) | SiaP(co««0] 
[TOKEY(^eK) I TOADDRESS(fli^rc55) | 

TONUMBERC wMm^r) | COUNT(coMnO] 



REPRO Parameters 
Required Parameters 






INFILE( dname [/ password ][bENVIRONMENT(DUMMY) ] ) | 
INDATASETC entryname [ / password ] [ bENVIRONMENT(DUMMY) ] ) 
identifies the data set to be copied. See the section "Copying Data Sets" 
for information on the types of data sets which can be copied, specific 
copy functions, and restrictions. 

INFDLEC dname [/ password ] ) 

specifies the name of the DD statement that identifies the data set to be 
copied. You can copy a base cluster in alternate-key sequence by 
specifying a path name as the data set name in the DD statement. See 
the section "Copying Data Sets" for information on DCB parameters 
required for nonVSAM data sets. 

Abbreviation: IFILE 

INDATASETC entryname [ / password ] ) 

specifies the name of the entry to be copied. If INDATASET is 
specified, the entryname is dynamically allocated. You can copy a base 
cluster in alternate-key sequence by specifying a path name for 
entryname. 

Abbreviation: IDS 

password 

is the read- or higher-level password of the data to be copied. If the 
data set is password protected, the read password must be suppUed. If 
a catalog is to be copied, the master password is required. Passwords 
are applicable only to VSAM data sets. 

ENVIRONMENT (DUMMY) 

specifies that dummy ISAM records are to be copied. Dummy records 
are records with hexadecimal *FF' in the first byte. If you do not include 
this parameter, dummy records will be ignored during the copy 
operation. See OS/VS Virtual Storage Access Method (VSAM) 
Programmer's Guide for further information. If ENVIRONMENT is 
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Optional Parameters 



not coded, dummy records are not copied. 

Abbreviations: ENV and DUM 

OUTFILE( dname [/ password ]) | 
OUTDATASET( entryname [ / password ] ) 

identifies the output data set. ISAM data sets cannot be specified as output 

data sets. 

OUTFILE( dname [ / password ] ) 

specifies the name of a DD statement that identifies the output data set. 
For VSAM data sets, the data set name can be that of a path. See the 
section "Copying Data Sets" for information on DCB parameters 
required for nonVSAM data sets. If the DD statement identifies a 
SYSOUT data set, the attributes must match those specified in the 
section: "Output Data Sets." 

Abbreviation: OFILE 

OUTDATASET( entryname [ / password ] ) 

specifies the name of the output data set. If OUTDATASET is 
specified, the entryname is dynamically allocated. For VSAM data sets, 
entryname can be that of a path. 

password 

specifies the update- or higher-level password for a 
password-protected output data set or path. 

Abbreviation: ODS 



FROMKEYC key ) \ FROMADDRESS( address ) | 

FROMNUMBERC number ) | SKIP( count ) 

specifies the location in the input data set from which copying is to start. 
You can use only one of the four possible choices. If no value is coded, the 
listing begins with the fkst logical record in the data set. The only 
parameter that can be coded for a SAM data set is SKIP. None of these 
parameters can be specified if you are copying a catalog; the entire catalog 
must be copied. 

FROMKEY{ key ) 

specifies the key of the first record you want copied. You can specify 
generic keys — that is, keys shorter than that defined for the data set. If 
you specify generic keys, copying begins at the first record whose key 
matches that portion of the key you specified. (You cannot specify a 
key longer than that defined for the data set. If you do, the data set is 
not copied.) If the specified key is not found, the next higher key is used 
as the starting point for copying. 

FROMKEY can be specified only when an alternate index, a 
key-sequenced VSAM data set, or an indexed-sequential (ISAM) 
nonVSAM data set is being copied. If FROMKEY is specified for the 
starting location, TO ADDRESS cannot identify the ending location. 

key can contain 1 to 255 EBCDIC characters, key must be enclosed in 
single quotation marks if it contains commas, semicolons, blanks, 
parentheses, or slashes. A single quotation mark within a key must be 
coded as two single You can code key in hexadecimal form where the 
hexadecimal value is enclosed in single quotation marks and preceded by 
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an X — for example, X'C2C1C8'. key can contain up to 255 
hexadecimal characters. 

Abbreviation: FKEY 

FROMADDRESSC address ) 

specifies the relative byte address (RBA) of the first record you want 
copied. The RBA value must be the beginning of a logical record. If you 
specify this parameter for key-sequenced data, the records will be 
copied in physical sequential order instead of in logical sequential order. 
FROMADDRESS can be coded only for VSAM key-sequenced or 
entry-sequenced data sets or components. FROMADDRESS cannot be 
specified when the data set is being accessed through a path. 
FROMADDRESS cannot be specified for a key-sequenced data set with 
spanned records if any of those spanned records are to be accessed. 

Abbreviation: FADDR 

FROMNUMBERC number ) 

specifies, for a relative-record cluster, the relative-record number of the 
first record you want copied. 

Abbreviation: FNUM 

SKIPC count ) 

specifies the number of logical records you want to skip before 
beginning to copy records. For example, if you want to copy beginning 
with record number 500, you specify SKIP(499). SKIP should not be 
specified when you access the data set through a path; the results are 
unpredictable. 

address, number, and count can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n') form; the expression cannot be longer than one 
fuUword (eight decimal or hexadecimal numbers, or 32 binary numbers). 

REPLACE I NOREPLACE 

specifies whether a record in the source cluster (INFILE or INDATASET) 
is to replace a record in the target cluster (OUTFILE or OUTDATASET) 
when the source cluster is copied into the target cluster. When a 
key-sequenced cluster or relative-record cluster (that is, the source cluster) 
is copied, its records might have keys or relative-record numbers identical 
to the keys or relative-record numbers of data records in the target cluster. 

REPLACE cannot be used if the output data set is identified as a path 
through an alternate index, or if the output data set is a base cluster whose 
upgrade set includes an alternate index defined with the unique-key 
attribute. 

Since the catalog Reload function automatically performs a Replace 
function, REPLACE | NOREPLACE is ignored if the output data set is a 
VSAM catalog. 

When a key-sequenced cluster, other than a catalog, is copied and you 
specify: 

• REPLACE, each source record whose key matches a target record's key 
replaces the target record. Otherwise, the source record is inserted into 
its appropriate place in the target cluster. 
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• NOREPLACE, target records aren't replaced by source records. Each 
source record whose key matches a target record's key is not inserted 
into the target data set and a "duplicate record" message is issued. 

When a relative-record cluster is copied and you specify: 

• REPLACE, each source record whose relative-record number identifies 
a data record (rather than an empty slot) in the target cluster replaces 
the target data record. Otherwise, the source data record is inserted into 
the empty slot its relative-record number identifies. 

• NOREPLACE, target records aren't replaced by source records. Each 
source record whose relative-record number identifies a target data 
record instead of an empty slot is not inserted into the target data set 
and a "duplicate record" message is issued. 

Abbreviations: REP and NREP 

REUSE I NOREUSE 

specifies whether the output data set is to be opened as a reusable data set. 
This parameter is vaUd only for VSAM data sets. When REUSE is 
specified, the output data set, specified with OUTFILE or 
OUTDATASET, is opened as a reusable data set regardless of whether or 
not it was defined as REUSE (see the DEFINE CLUSTER conmiand 
description). If the data set was defined as REUSE, its high-used relative 
byte address (RBA) is reset to zero (that is, the data set is effectively 
empty) and the operation proceeds. If REUSE is specified and the data set 
was originally defined with the NOREUSE option, the data set must be 
empty; otherwise, the REPRO command terminates with an error message. 

If the NOREUSE attribute is specified (either explicitly or by default) and ^ 

OUTFILE or OUTDATASET identifies a nonempty data set, records are \ 

written at the end of an entry-sequenced data set. Processing of 
key-sequenced and relative-record data sets is controlled by the 
REPLACE/NOREPLACE option used. 

Abbreviations: RUS and NRUS 

TOKEY( key ) | TOADDRESS( address ) | 

TONUMBER( number ) | COUNT( count ) 

specifies the location in the data set being copied at which copying is to 
stop. You caii use only one of the four choices. If no value is coded, the 
copying ends with the logical end of the data set or component. The only 
parameter that can be specified for a sequential data set is COUNT. None 
of these parameters can be specified if you are copying a catalog; the entire 
catalog must be copied. The location at which the copying is to end must 
foUow the location at which it is to begin. 

TOKEY( key ) 

specifies the key of the last record you want copied. You can specify 
generic keys — that is, keys shorter than that defined for the data set. If 
you specify generic keys, copying stops after the last record is copied 
whose key matches that portion of the key you specified. (You cannot 
specify a key longer than that defined for the data set. If you do, the 
data set is not copied.) If the specified key is not found, the next lower 
key is used as the stopping point for copying. 

TOKEY can be specified only when an alternate index, a key-sequenced 
VSAM data set, or an indexed-sequential (ISAM) nonVSAM data set is 
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being copied. If FROMADDRESS was specified for tlie starting 
location, TOKEY cannot be specified for the ending location, 

key can contain 1 to 255 EBCDIC characters, key must be enclosed in 
single quotation marks if it contains commas, semicolons, blanks, 
parentheses, or slashes. A single quotation mark within a key must be 
coded as two single quotation marks. You can code key in hexadecimal 
form where the hexadecimal value is enclosed in single quotation marks 
and preceded by an X — for example, X'C2C1C8'. key can contain up 
to 255 hexadecimal characters. 

TOADDRESS( address ) 

specifies the relative byte address (RBA) of the last record you want 
copied. Unlike FROMADDRESS, the RBA value does not need to be 
the begiiming of a logical record. The entire record containing the 
specified RBA is copied. If you specify this parameter for a 
key-sequenced data set, the records will be copied in physical sequential 
order instead of in logical sequential order. 

TO ADDRESS cannot be specified as the ending location if FROMKEY 
was specified as the starting address. TO ADDRESS can be used only 
with VSAM key-sequenced or entry-sequenced data sets or 
components. TO ADDRESS cannot be specified when the data set is 
accessed through a path. TO ADDRESS cannot be specified for a 
key-sequenced data set with spanned records if any of those spanned 
records are to be accessed. 

Abbreviation: TADDR 

TONUMBER( number ) 

specifies the relative-record number of the last record you want copied. 
TONUMBER can be specified only when you copy a relative-record 
cluster. 

Abbreviation: TNUM 

COUNT( count ) 

specifies the number of logical records you want copied. COUNT 
should not be specified when you access the data set through a path; the 
results are unpredictable. 

address, number, and count can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n') form; the expression cannot be longer than one 
fuUword (eight decimal or hexadecimal numbers, or 32 binary numbers). 
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REPRO Examples 

Copy Records Into a VSAM Cluster: Example 1 



In this example, records from an indexed-sequential data set, ISAMDSET, are 
copied into key-sequenced VSAM cluster, D40.EXAMPLE.KSDS1. 

//REPRO 1 JOB 

//JOBCAT DD DSNAME=D27UCAT2,DISP=SHR 
//STEP1 EXEC PGM=IDCAMS 

//INDSET1 DD DSNAME=ISAMDSET,DISP=OLD, 
// DCB=( DSORG=IS , BUFN0=6 ) 

//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
REPRO - 

INFILEdNDSETI ) - 

OUTDATASET( 04 0. EXAMPLE. KSDS1 ) 
/* 

The job control language statements are: 

• JOBCAT DD, which makes a catalog available for this job: D27UCAT2. 

• INDSETl DD, which describes the indexed-sequential data set, 
ISAMDSET, that contains the input records. The BUFNO parameter 
specifies the number of buffers assigned to the ISAM data set. This 
improves performance when the ISAM data set's records are accessed. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The REPRO command copies all records from the input data set, 
ISAMDSET, to the output data set, D40.EXAMPLE.KSDS1. Its parameters 
are: 

. INFILE, which points to the INDSETl DD statement. The INDSETl DD 
statement identifies the source, or mput, data set: ISAMDSET. 
ISAMDSET is an indexed-sequential data set. 

• OUTDATASET, which identifies the key-sequenced VSAM cluster into 
which the input records are to be copied. This data set is dynamically 
allocated by Access Method Services. 
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REPRO 

Copy Records Into a VSAM Cluster: Eiuunple 2 

In this two-part example, data records are copied from the nonVSAM data set 
SEQ.D27V, a sequential data set, into a key-sequenced VSAM cluster, 
D40.MYDATA. Next, records are copied from the key-sequenced cluster, 
D40.MYDATA, into an entry-sequenced cluster, ENTRY. 

//REPR02 JOB . . . 

//JOBCAT DD DSNAME=MYCAT,DISP=SHR 
//STEP1 EXEC PGM=IDCAMS 

//INPUT DD DSNAME=SEQ.D27V,DISP=SHR,DCB=(BUFNO=6) 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
REPRO - 

INFILEC INPUT) - 

OUTDATASET( D40 . MYDATA ) 

/* 

//STEP2 EXEC PGM=IDCAMS 
//INPUT DD DSNAME=MYDATA,DISP=OLD 
//OUTPUT DD DSNAME=ENTRY,DISP=OLD 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
REPRO - 

INFILEC INPUT ) - 

OUTF I LE( OUTPUT ) - 

FROMKEY(DEAN) - 

TOKEY( JOHNSON) 
/* 

STEPl: Access Method Services copies records from a sequential data set, 
SEQ.D27V, mto a key-sequenced VSAM cluster, D40.MYDATA. STEPl's 
job control language statements are: 

• JOBCAT DD, which makes the catalog MYCAT available for this job. 

• INPUT DD, which identifies the sequential data set, SEQ.D27V, that 
contains the input records. The BUFNO parameter specifies the number of 
buffers assigned to the sequential data set. This improves performance 
when the data set's records are accessed. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

STEPl's REPRO command copies all records from the input data set, 
SEQ.D27V, to the output data set, D40.MYDATA. Its parameters are: 

• INFILE, which pomts to the INPUT DD statement. The INPUT DD 
statement identifies the source, or input, data set. 

• OUTDATASET, which identifies the key-sequenced cluster into which the 
input records are to be copied. The data set is dynamically allocated by 
Access Method Services. 

STEP2: Access Method Services copies some of the records of the 
key-sequenced cluster D40.MYDATA into another entry-sequenced cluster, 
ENTRY. STEP2's job control language statements are: 

• JOBCAT DD, which applies to this job step as well as to STEPl. 

• INPUT DD, which identifies the key-sequenced cluster, D40.MYDATA, 
that contains the input records. 
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• OUTPUT DD, which identifies the entry-sequenced cluster, ENTRY, that 
the records are copied into. 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

STEP2's REPRO command copies records from the input data set, 
D40.MYDATA, to the output data set, ENTRY. Only those records with key 
values from DEAN to, and including, JOHNSON are copied. The REPRO 
command's parameters are: 

• INFILE, which points to the INPUT DD statement. The INPUT DD 
statement identifies the source, or input, key-sequenced cluster. 

. OUTFILE, which points to the OUTPUT DD statement. The OUTPUT 
DD statement identifies the entry-sequenced cluster into which the input 
records are to be copied. 

• FROMKJEY and TOKEY, which specify the lower and upper key 
boundaries. Only those records with key values from DEAN to, and 
including, JOHNSON are copied. 

If ENTRY already contains records, VSAM merges the copied records with 
ENTRY'S records. A subsequent job step could resume copying the records 
into ENTRY, beginning with the records with key greater than JOHNSON. If 
you subsequently copied records with key values less than DEAN into 
ENTRY, VSAM merges them with ENTRY'S records. 
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REPRO 



Copy a Catalog: Example 3 



In this example, a catalog is copied to illustrate the copy-catalog procedure. 



//COPYCAT JOB 


• . . 


//STEP1 EXEC 


PGM=IDCAMS 


//SYSPRINT DD 


SYSOUT=A 


//SYSIN DD 


* 


DEFINE 


USERCATALOG - 



( NAME { COP YUCAT ) - 

MASTERPW( UCATMPW ) - 
UDATEPW( UCATUPW ) - 
FOR( 365 ) - 
VOLUME ( VSERO 6 ) - 
CYLINDERS ( 100 10) ) 
DATA - 







{CYLINDERS(20 10) ) - 




INDEX 


(CYLINDERS! 10) ) - 




CATALOG - 


/* 

//STEP2 




( AMASTCAT/MRCATPW2 ) 


EXEC 


PGM=IDCAMS 


//STEPCAT 


DD 


DSNAME=COP YUCAT , DISP=OLD 


// 


DD 


DSNAME=MYCAT , DISP=OLD 


//SYSPRINT 


DD 


SYSOUT=A 


//SYSIN 


DD 


« 


REPRO 


- 





INDATASETC MYCAT ) - 

OUTDATASET( COPYUCAT/UCATMPW ) 
EXPORT - 

MYCAT - 

DISCONNECT 
/* 

//STEP3 EXEC PGM=IDCAMS 
//STEPCAT DD DSNAME=COPYUCAT,DISP=SHR 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
LISTCAT 

/* 

//STEP4 EXEC 
//SYSPRINT DD 
//SYSIN DD 
DELETE - 

MYCAT - 

CLUSTER - 

PURGE - 

CATALOG ( COPYUCAT/UCATMPW 

/* 

//STEPS EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
DEFINE ALIAS - 

(NAME (MYCAT) - 
RELATE ( COP YUCAT ) ) 
/* 



PGM=IDCAMS 
SYSOUT=A 



% 
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SXEPl: 

A user catalog, COPYUCAT, is defined on volume VSER06. The catalog 
entries in MYCAT will be copied into COPYUCAT. STEPl's job control 
statement is: 

• SYSPRINT DD, which is required in all Access Method Services job steps. 
The SYSPRINT DD statement identifies the output device to which Access 
Method Services messages to the programmer are to be sent. 

The DEFINE USERCATALOG command defines the user catalog, 
COPYUCAT. Its parameters are: 

• NAME, which specifies the name of the new catalog, COPYUCAT. 

• MASTERPW and UPDATEPW, which specify the master and update level 
passwords for the catalog. 

• FOR, which specifies that the catalog is to be retained for 365 days. 

• VOLUME, which specifies that the catalog is to reside on volume 
VSER06. 

• CYLINDERS, which specifies that the catalog's data space is initially to be 
100 cylinders. When the data space is extended, it is to be extended in 
increments of 20 cylinders. Part of the data space contains the catalog, 
COPYUCAT. The rest of the data space is available for suballocated 
VSAM clusters. 

. DATA(CYLINDERS) and INDEX( CYLINDERS) specify that the 
catalog itself is initially to occupy 30 cylinders, VSAM determines the 
proportion of space to allocate to the catalog's data and index components. 
When the catalog's data component is extended, it is to be extended in 
increments of 10 cylinders. 

• CATALOG, which specifies that a user catalog connector entry is to be 
built and written into the AMASTCAT catalog. The user catalog connector 
entry points to COPYUCAT. 

STEP2: 

Access Method Services copies the contents of MYCAT into COPYUCAT. 
STEP2's job control statements are: 

• STEPCAT DD, which makes two catalogs available for this job step: 
COPYUCAT and MYCAT. The DD statements that identify the catalogs 
are concatenated. 

. SYSPRINT DD (see STEPl above). 
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REPRO 

The REPRO command copies all records from MYCAT into COPYUCAT. 
Access Method Services treats each catalog as a key-sequenced VSAM cluster 
and copies each catalog record. Consequently, the first thirteen catalog 
records of MYCAT, which describe MYCAT as a key-sequenced cluster, are 
also copied into COPYUCAT. Entries from MYCAT are written into 
COPYUCAT beginning with catalog record 14 (that is, after the thirteen 
self -describing records of COPYUCAT). The REPRO command's parameters 
are: 

• INDATASET, which identifies the source, or input, data set: MYCAT. 
VSAM assumes that MYCAT is cataloged in either MYCAT or 
COPYUCAT. 

• OUTDATASET, which identifies the receiving data set: COPYUCAT. 
VSAM assumes that COPYUCAT is cataloged in either COPYUCAT or 
MYCAT. 

The EXPORT command removes MYCAT's user catalog connector entry 
from the master catalog. MYCAT's cataloged objects are now not available to 
the system. (STEPS builds an aUas entry that relates MYCAT to 
COPYUCAT, making the cataloged objects available to the system again.) 

STEP3: 

Access Method Services lists the name of each entry in the new catalog, 
COPYUCAT. The STEPCAT DD statement identifies the catalog to be 
listed. 

STEP4: 

Access Method Services removes the entries in COPYUCAT that describe 
MYCAT as a key-sequenced cluster. (See STEP2 description above.) The 
DELETE command's parameters are: 

• MYCAT, which identifies the object to be deleted. 

• CLUSTER, which specifies that MYCAT is cataloged as a cluster in 
COPYUCAT. MYCAT's cluster, data, and index entry are removed from 
COPYUCAT. 

• PURGE, which specifies that MYCAT is to be deleted regardless of a 
specified retention period or date. 

• CATALOG, which specifies that MYCAT is cataloged in COPYUCAT. 
COPYUCAT's master password, UCATMPW, is required to delete its 
catalog entries. 

STEPS: 

Access Method Services builds an alias entry that relates MYCAT to 
COPYUCAT. Because no CATALOG parameter or JOBCAT or STEPCAT 
DD statement identifies the catalog that is to contain the alias entry, VSAM 
assumes the entry is to be written into the master catalog. 

When MYCAT was defined, it was defined on volume VSER04. Its catalog 
entries describe VSAM objects on that volume. COPYUCAT is defined on 
volume VSER06. Because MYCAT was copied into COPYUCAT (and 
MYCAT no longer exists as a user catalog), COPYUCAT entries now 
describe VSAM objects on volumes VSER04 and VSER06. 
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Unload a VSAM User Catalog: Example 4 



This example shows how a VSAM user catalog can be unloaded to tape using 
the catalog unload/reload feature of the REPRO command. 

//UNLOAD JOB 

//JOBCAT DD DSNAME=D27UCAT2,DISP=OLD 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 

//CATIN DD DSNAME=D27UCAT2,DISP=OLD 
//CATOUT DD DSNAME=PORTABLE . TAPE , LABEL= ( 1 , SL) , 
// DISP=NEW,UNIT=2400-3,VOL=SER=TAPE01 , 
// DCB=( DEN=3 , RECFM=VB , LRECL=5 1 6 , BLKSIZE=5 1 64 ) 
//SYSIN DD * 
REPRO - 

INFILE(CATIN/UCATMRPW) - 
OUTFILE( CATOUT) 
/* 

The job control language statements are: 

• JOBCAT DD, which is required, and which identifies and allocates the 
user catalog as the job catalog. 

• CATIN DD, which describes and allocates the user catalog, D27UCAT2, 
as a VSAM data set to be opened and used by the REPRO command as 
the source data set for the unload operation. 

• CATOUT DD, which describes and allocates a magnetic tape file to 
contain the copy of the catalog. The DCB parameters must be specified as 
shown. The BLKSIZE parameter can be any multiple of LRECL, plus 4, 
where the minimum LRECL=505. 

The REPRO command causes the VSAM user catalog D27UCAT2 to be 
unloaded (that is, copied) to a magnetic tape file. The REPRO command's 
parameters are: 

• INFILE, which is required, and which identifies the user catalog as an 
input, or source, VSAM data set. The catalog's master password is required 
to open it as a data set. 

• OUTFILE, which is required, and which describes the magnetic tape file, 
or target data set that is to contain the catalog's copy. 



Reload an Unloaded VSAM User Catalog: Example 5 



This example shows how a VSAM user catalog can be reloaded from the 
backup copy created in the previous example using the catalog unload/reload 
feature of the REPRO command. 

//RELOAD JOB 

//JOBCAT DD DSNAME=D27UCAT2,DISP=OLD 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 

//CATIN DD DSNAME=PORTABLE . TAPE , LABEL=( 1 , SL ) , 
// DISP=OLD,UNIT=2400-3,VOL=SER=TAPE01 ,DCB=DEN=3 
//CATOUT DD DSNAME=D27UCAT2,DISP=OLD 
//SYSIN DD * 
REPRO - 

INFILE (CATIN) - 

OUTF I LE ( CATOUT/UC ATMRPW ) 

/* 
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REPRO 

The job control language statements are: 

• JOBCAT DD, which is required and which describes and allocates the user 
catalog to be reloaded. The JOBCAT statement specifies that D27UCAT2 
is the job catalog. 

• CATIN DD, which describes and allocates the magnetic tape file that 
contains the unloaded copy of the catalog. Since a standard label tape is 
used, DCB parameters of record format, recordsize, and blocksize need not 
be specified. For a non-labeled tape, the same parameters as in the 
previous example must be specified. 

• CATOUT DD, which describes the user catalog as a VSAM data set to be 
opened and used by REPRO as the target data set for the reload operation. 

The REPRO command causes a VSAM user catalog to be reloaded from the 
backup copy created in the previous example. The REPRO command's 
parameters are: 

• INFILE, which is required, and which identifies the magnetic tape file that 
contains the unloaded, or backup, copy of the user catalog. 

• OUTFILE, which is required and which identifies the user catalog as a 
VSAM data set to be opened for record processing. The master password 
allows opening the catalog as a data set. 
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RESETCAT 



MJi^I^ll* 1. C^ A 1 



RESETCAT Parameters 

Required Parameters 



The format of the RESETCAT command is: 



RESETCAT 



CATALOG( catname [/password ][ b dname ]) 
{CVLAFllMSiidnamel [bALL| bNONE]) 
[idmmel [b ALL | bNONE])...]) | 
CRAVOLUMES(( volser [ b devtype ]) 
[{wiser [b devtype ])...])} 
[IGNORE I NOIGNORE ] 
[MASTElKPWipassword )] 
[WORKCATC catname [/password ])] 
[WOBXFlLEidname [/password])] 



RESETCAT may be abbreviated: RCAT. 



CATALOG ( catname [ /password ] [ dname ] ) 

identifies the catalog to be reset. The catalog specified by catname must 
have the RECOVERABLE attribute. Exclusive control of the catalog is 
required throughout the duration of the conmiand; also, no VSAM data 
sets cataloged in the catalog may be open. The master catalog may not be 
reset while it is in use as a master catalog. 

password 

specifies the catalog's master password. If the catalog is 
password-protected, you must specify the master password of the 
catalog. 

dname 

specifies the name of the DD statement for the catalog being reset. If 
dname is not specified, the catalog will be dynamically allocated. It must 
also be specified m a JOBCAT or STEPCAT. 

Abbreviation: CAT 

CRAFILES ( ( dnamel [ b AIX | bNONE ]) ...) 

specifies a list of DD statements which identify the volumes and devices to 
be used to reset the catalog. Each volume contains a CRA which has a 
copy of the catalog records describing the VSAM objects on that volume. 
ALL specifies that the catalog records in the CRA on the volume specified 
by dnamel are to be reset. If a volume contains a multivolume data set 
whose catalog entry is being reset, other volumes of that multivolume data 
set may be needed during the reset operation; you should specify these via 
additional dnamel parameters. Use the NONE subparameter, if you do 
not want the entries in these additional volumes to be used to reset the 
catalog. If a volume is needed and you do not specify the DD statements 
provided by CRAFILES, it will be allocated dynamically, and wiU assume 
the NONE attribute. 
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Optional Parameters 



CRAVOLUMES ( ( wiser [h devtype ])..,) 

specifies the volume serial numbers and corresponding device types of the 
volumes used in resetting the catalog. Each volume contains a catalog 
recovery area (CRA) which has a copy of the catalog records that describe 
the objects on the volume. The volume is allocated dynamically. 

devt;^e 

specifies the device type for the associated volser. If you do not specify 
devtype, the volume must be mounted and on a unit marked 
permanently resident or reserved. If you specify a generic name for 
devtype, the volume need not be mounted. 

If a volume contains a multivolume data set whose catalog entry is being 
reset, other volumes of that multivolume data set may be needed during 
the reset operation; if needed and not specified for reset, these volumes 
will be allocated dynamically. Dynamically allocated volumes assume the 
NONE attribute as described for the CRAFILES parameter. 

Abbreviation: CRAVOL 



IGNORE I NOIGNORE 

specifies whether RESETCAT should continue processing and force the 
reset when certain errors are encountered. These errors may be: 

• I/O error in the catalog 

• I/O error in the CRA 

• The volume record or its extensions in the CRA are in error. 

When you specify IGNORE, the RESETCAT command will try to recover 
as much information as possible and reset the catalog's description of those 
data sets on the specified volumes. For example, if IGNORE is specified 
and an I/O error occurs while processing a record from a CRA, that record 
will be ignored. In the process, data sets that could not be recovered on a 
particular volume would be marked unusable on that volume, and the space 
that was assigned to them would be freed. NOIGNORE specifies that 
these errors result in immediate termination. 

Abbreviations: IGN and NIGN 

MASTERPW ( password ) 

specifies the master catalog's master password. The master catalog's master 
password is required when the master catalog is password protected. 

Abbreviation: MRPW 

WORKCAT ( catname [ /password ] ) 

specifies the name of the catalog in which RESETCAT defines the 
WORKFILE. This catalog must not be the same as the catalog being reset. 
If the catalog is password-protected, the update or higher level password is 
required. The catalog must be specified in a JOBCAT or STEPCAT DD 
statement. If you do not specify the WORKCAT parameter, the catalog 
will be chosen using existing rules for "Order of Catalog Use: DEFINE" in 
the chapter "Creating and Cataloging Objects." Further constraints must 
be followed if you do not specify the WORKCAT parameter, that is, it 
must be the first DD statement in the JOBCAT or STEPCAT DD 
statement concatenation. However, if the work file catalog is the master 
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RESETCAT 

catalog, then you must specify the WORKCAT parameter and it must be 
the last DD statement in the JOBCAT or STEPCAT DD statement 
concatenation. The resultant catalog must not be the same one being reset. 

Abbreviation: WCAT 

WORKFILE ( dname [ /password ] ) 

specifies the name of a DD statement that identifies a VSAM data set 
name and a list of volume serial niunbers of volumes containing VSAM 
data spaces and units to be used by RESETCAT for a work file. These 
volumes must be owned by the catalog in which the work file is defined. 
This data set will be defined by RESETCAT and used as temporary 
storage while processing the command; it will be deleted at the end of the 
command. The data set must not be already defined. Space requirements 
for the data set are noted in "WORKFILE Space Requirements." If you do 
not specify WORKFILE, IDCUTl is used as a default dname, 

password 

If you desire, you may specify password, a password to be used by 
RESETCAT to password-protect the workfile. Since the work file will 
contain a copy of the catalog records, it may contain security-sensitive 
information. The password you specify will become the work file's 
master password. You may specify the password only if dname is 
explicitly specified. 

Abbreviation: WFILE 
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RESETCAT Examples 
Resetting a Catalog: Example 1 



// 


DD 


//IDCUT1 


DD 


// 


V< 


//CRAV0L1 


DD 


//CRAV0L2 


DD 


//DDCAT 


DD 


//SYSIN 


DD 



This example illustrates the use of RESETCAT to reset a catalog 
(USERCATl), one of whose owned volumes (VSEROl) has been restored. 
The other volume owned by USERCATl is VSER02. 

//RECOVER JOB . . . 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//STEPCAT DD DSN=USERCAT1 ,DISP=OLD 
DSN=AMASTCAT , DISP=OLD 
DSN=WORKFILE , DI SP=OLD , 
V0L=SER=2 31401, UNIT=2 3 1 4 , AMP= ' AMORG ' 
DISP=OLD,VOL=SER=VSER01 ,UNIT=2314 
DISP=OLD , VOL=SER=VSER02 , UNIT=23 1 4 
DSN=USERCAT1 ,DISP=OLD 
* 
RESETCAT - 

CATALOG (USERCATl /MASTER DDCAT) - 
CRAFILES( (CRAV0L1 ALL) ( CRAV0L2 NONE)) - 
WORKCAT ( AMAS TCAT/MCATMRPW ) - 
MASTERPW( MCATMRPW ) - 
IGNORE 
/* 

The job control language statements are: 

. STEPCAT DD, which makes the user catalog, USERCATl, and the 
master catalog, AMASTCAT, available for the step. These catalogs must 
be available for the catalog to be reset and for the work file to be defined, 
respectively. Note that when the work file is to be defined in the master 
catalog, the master catalog must be last in the concatenation and the 
catalog name is suppUed via the WORKCAT parameter. 

• IDCUTl DD, which identifies the data set to be used for the work file. 

• CRAVOLl DD, which identifies and allocates a volume whose catalog 
recovery area is to be used ro reset the catalog. 

• CRAVOL2 DD, which identifies and allocates a volume whose catalog 
recovery area may change as a result of resetting the catalog recovery area 
on volume VSEROl. This volume is not reset in the catalog. 

• DDCAT DD, which allocates the catalog to be reset. 

The RESETCAT command causes catalog USERCATl to be reset from the 
catalog recovery area on VSEROl. The RESETCAT command's parameters 
are: 

• CATALOG, which identifies the catalog to be reset. The master password 
of the catalog is required to update the catalog. The DD statement for the 
catalog is also identified. 

• CRAFILES, which specifies a list of DD statements which identify the 
volumes to be used to reset the catalog. ALL specifies that the catalog 
records in the CRA on the volume specified by the CRAVOLl DD 
statement are to be reset (in the catalog). NONE allows the CRAVOL2 
DD statement to be specified for a CRA volume which is not to be used 
for reset, but which may be needed as a result of the reset (for example, a 
multivolume data set resides on a reset volume and on a non-reset volume). 
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Resetting a Catalog: Example 2 



RESETCAT 

WORKCAT, which specifies the name of the catalog in which to define 
the work file. WORKCAT must be specified if the work file is to be 
defined in the master catalog. 

IGNORE, which specifies that RESETCAT should force the reset of the 
catalog despite certain errors which may be encountered during the 
RESETCAT processing. 



This example illustrates the use of RESETCAT to reset a catalog 
(USERCATl) after the volume (VSEROO) on which the catalog resides has 
been restored. The volumes owned by USERCATl, VSEROl, and VSER02 
have been determined to be out of synchronization with the catalog by 
running a LISTCRA with the COMPARE option for all volumes owned by 
USERCATl. 

//RECOVER JOB . . . 

//JOBCAT DD DSN=USERCAT2,DISP=0LD 
// DD DSN=USERCAT1 ,DISP=OLD 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 

//WORKF DD DSN=WORKEILE , DISP=OLD , UNIT={ 2314,2), 
// VOL=SER=( 23 140 1,231 402 ),AMP='AMORG' 

//SYSIN DD * 
RESETCAT - 

CATALOGC USERCATl ) - 

CRAVOLSC (VSEROl 2314)(VSER02 2314)) - 

WORKFILE(WORKF/WRKPSW)- - 

NOIGNORE 
/* 

The job control language statements are: 

• JOBCAT DD, which makes the user catalogs USERCAT2 and 
USERCATl available for the job. These catalogs must be available for the 
workfile to be defined and for the catalog to be reset, respectively. 

• WORKF DD, which identifies the data set to be used for the work file. 

Note: All other required volumes will be dynamically allocated by 
RESETCAT. 

The RESETCAT command causes catalog USERCATl to be reset from the 
catalog recovery areas on VSEROl and VSER02. The RESETCAT 
parameters are: 

• CATALOG, which identifies the catalog to be reset. 

• CRAVOLS, which specifies a Ust of volumes and their device types to be 
used to reset the catalog. 

• WORKFILE, which specifies the DD statement for the work file and a 
password to be used as the work file's master password. 

• NOIGNORE, which specifies that RESETCAT should not force the reset 
of the catalog if certain errors are encountered. 
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Resetting a Catalog: Example 3 



This three-part example illustrates the use of RESETCAT to reset a catalog 
(USERCATl on volume VSEROO) which must be reallocated on a different 
volume (VSER03). Such a situation may occur when an irreparable physical 
failure has befallen the catalog. In this example, the catalog recovery area for 
the damaged catalog volume is assumed to be accessible and valid and thus 
included for reset in the newly defmed catalog. Note that the newly defined 
catalog bears the same name as the damaged catalog. The other volumes 
owned by USERCATl are VSEROl and VSER02. The catalog is fbst 
disconnected, then redefined, 

//DISC JOB . . . 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//STEPCAT DD DSN=USERCAT1 ,DISP=OLD 

//SYSIN DD * 

EXPORT USERCATl DISCONNECT 

//STEP2 EXEC PGM=IDCAMS 
//SYSPRINT DD ■ SYSOUT=A 

//UCATDD DD VOL=SER=VSER03 , UNIT=3330 , DISP=OLD 
//CRAV0L1 DD VOL=SER=VSER01,UNIT=2314,DISP=OLD 
//CRAV0L2 DD VOL=SER=VSER02 ,UNIT=2314,DISP=OLD 
//SYSIN DD * 
DEFINE UCAT - 

(NAME (USERCATl) FILE ( UCATDD ) VOL(VSER03) - 

RECOVERABLE CYL( 20 1 ) ) - 

DATA( CYL( 10 1 ) ) INDEX( CYL( 1 ) ) 

PGM=IDCAMS 
SYSOUT=A 

DSN=USERCAT1 ,DISP=OLD 
DSN=AMASTCAT , DISP=OLD 
DSN=WORKFILE , DISP=OLD, UNIT=23 1 4 , 
VOL=SER=23 1401, AMP= ' AMORG ' 
* 
RESETCAT - 

CATALOG( USERCATl ) - 
WORKCAT( AMASTCAT ) - 

CRAVOLS( (VSEROO 3330) (VSEROl 2314)(VSER02 2314)) 
/* 

STEPl: 

The user catalog, USERCATl, is disconnected from the system by using the 
EXPORT command. 

STEPl: 

The user catalog, USERCATl, is redefined on the volume VSER03. 

STEP3: 

The user catalog USERCATl is reset from the previous catalog's owned 
volumes. 

The job control language statements are: 

• STEPCAT DD, which makes the user catalog, USERCATl, and the 
master catalog, AMASTCAT, available for the step. These catalogs must 
be available for the catalog to be reset, and for the work file to be defined, 
respectively. 

• IDCUTl DD, which identifies the data set to be used for the work file. 



//STEP3 


EXEC 


//SYSPRINT 


DD 


//STEPCAT 


DD 


//STEPCAT 


DD 


//IDCUTl 


DD 


// 


VOL^ 


//SYSIN 


DD . 
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RESETCAT 

The RESETCAT command causes the redefined catalog USERCATl to be 
reset from the catalog recovery areas on volumes VSEROO, VSEROl, and 
VSER02. The RESETCAT command's parameters are: 

• CATALOG, which identifies the catalog to be reset. 

• WORKCAT, which specifies the name of the catalog in which to define 
the workfile. WORKCAT must be specified if the work file is to be defined 
in the master catalog. 

• CRAVOLS, which specifies a list of volumes and their device types to be 
used to reset the catalog. 
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VERIFY 



VERIFY 



VERIFY Parameters 
Required Parameters 



The format of the VERIFY command is: 



VERIFY 



{¥lLE{dname{/ password^ \ 

DATASET(entryname [/password ])} 



VERIFY can be abbreviated: VFY 



FILE( dname [/ password ] ) 

dname specifies the name of a DD statement that identifies the cluster or 
component to be verified. 

password 

is the control or master password of a password-protected cluster or 
component or the master password of a password-protected catalog, 

DATASET( entryname [ / password ] ) 

specifies the name and password of the object to be verified. If DATASET 
is coded, the object is dynamically allocated. 

password 

is the control or master password of a password-protected object, or is 
the master password of the object's (password-protected) catalog. 

Abbreviation: DS 
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VERIFY Example 

Upgrading a Data Set's End-of-File Information: Example 1 



When a data set that was improperly dosed (that is, closed as a result of 
system failure) is opened, the VSAM Open routines set a return code to 
indicate that the data set's cataloged information might not be accurate. The 
user can upgrade the EOD and EOKR information (so that it is accurate 
when the data set is next opened) by closing the data set^ and issuing the 
VERIFY command: 

//VERIFY JOB . . . 

//JOBCAT ■ DD DSNAME=D27UCAT1 ,DISP=SHR 

//FIXEOD EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

LISTCAT ENTRIES(FAROUT) - 
ALL 

VERIFY DATASET( FAROUT ) 

LISTCAT ENTRIES (FAROUT) - 
ALL 
/* 

SYSPRINT is a DD statement required in all Access Method Services job 
steps to describe the output data set for messages. 

The first LISTCAT command lists the data set's cataloged information, 
showing the data set's parameters as they were when the data set was last 
closed properly. 

The VERIFY command updates the data set's cataloged information to show 
the data set's real EOD and EOKR values. 

The second LISTCAT command lists the data set's cataloged information 
again. This time, the EOD and EOKR information show the point at which 
processing stopped due to system failure. This information should help the 
user determine how much of his data was added correctly before the system 
failed. 

See "Appendix B: Interpreting LISTCAT Output Listings" for details on the 
order in which catalog records are to be listed and the meanings of the Hsted 
records. 



1 When the data set is opened (first OPEN after system failure), VSAM Open sets 
a "data set improperly closed" return code. When the data set is closed properly, 
VSAM Close resets the "data set improperly closed" indicator but does not 
upgrade erroneous catalog information that resulted from the system failure. 
Subsequently, when the data set is next opened, its EOD and EOKR information 
might still be erroneous (until VERIFY is issued to correct it), but VSAM Open 
sets the "data set opened correctly" return code. 
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CONTROLLING COMMAND EXECUTION 



This chapter describes: 



Condition Codes 



• IF-THEN-ELSE command sequence, which is used to control command 
execution on the basis of condition codes. 

• DO-END command sequence, which specifies more than one functional 
Access Method Services command and its parameters. 

• SET command, which is used to reset condition codes. 

• FARM command, which is used to specify diagnostic-aids and 
printed-output options. 

These commands cannot be used when Access Method Services is being 
executed under TSO. 



The condition codes that are tested in the IF-THEN-ELSE command 
sequence are: 

• 0, which indicates that the function was executed as directed and expected. 
Some informational messages may have been issued. 

• 4, which indicates that some problem was met in executing the complete 
function, but it was possible to continue. The continuation might not 
provide the user with exactly what he wanted, but no permanent harm will 
have been done by such continuation. A warning message was issued.- An 
example of the kind of problem encountered is: the system was unable to 
locate an entry in a LISTCAT command. 

• 8, which indicates that a requested function was completed, but major 
specifics were unavoidably bypassed. For example, an entry to be deleted 
or altered could not be found in the catalog, or a duplicate name was found 
while an entry was being defined and the define action was terminated. 

• 12, which indicates that the requested function could not be performed. 
This condition code is set as a result of a logical error. A logical error 
condition exists when inconsistent parameters are specified, when a too 
small or too large value is specified for key length, recordsize, or 
bufferspace, or when required parameters are missing. More information 
on logical errors that occur during VSAM record processing is in the 
OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide. 

• 16, which indicates that a severe error occurred that caused the remainder 
of the command stream to be flushed. This condition code might be set as 
a result, for example, of the following: a system output data set cannot be 
opened (a SYSPRINT DD statement was missing, for example); an 
unrecoverable error occurred in a system data set; or Access Method 
Services encountered improper IF-THEN-ELSE command sequences. 

The condition codes that are tested in the IF-THEN-ELSE command 
sequence and that can be set by the SET command cannot be passed from 
one job step to the next. However, the final maximum condition code is 
passed to the OS/VS system when the Access Method Services processor 
returns control to the system. 
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IF'THEN'ELSE Command Sequence 



The IF-THEN-ELSE command sequence is used to control command 
execution. 

The format of the IF-THEN-ELSE command sequence is: 




{LASTCC I MAXCC}lh]comparand[h]number 
TBEN[h command \ 

DO 

command set 

END] 
[ELSE[h command \ 

DO 

command set 

END]] 



where: 

IF 

specifies that one or more functional commands is to be executed based on 
a test of a condition code. The condition code is set by a SET command or 
is set to reflect the completion status of previous functional commands. 

LASTCC 

specifies that the condition code value that resulted from the immediately 
previous function command is to be compared as indicated by the 
comparand number to determine whether the THEN action is to be 
performed. See "Condition Codes" earlier in this chapter for the meaning 
of condition codes. 

MAXCC 

specifies that the maximum condition code value that has been established 
by any previous function command or by a SET command is to be 
compared as indicated by the comparand number to determine whether the 
THEN action is to be performed. See "Condition Codes" earlier in this 
chapter for the meaning of condition codes. 

comparand 

specifies the comparison to be made between the variable and the 
following number. This can be any of six possible comparisons: 

Equal, specified as "=" or "EQ" 

Not equal, specified as "-i=" or "NE" 

Greater than, specified as ">" or "GT" 

Less than, specified as "<" or "LT" 

Greater than or equal, specified as ">=" or *GE" 

Less than or equal, specified as "<=" or "LE" 

number 

specifies the decimal integer that is to be compared with MAXCC or 
LASTCC. The number can be up to ten digits long. Values greater than 16 
are reduced to 16; both LASTCC and MAXCC are initialized to zero 
upon entry to Access Method Services. See "Condition Codes" earlier in 
this chapter for the meaning of condition codes. 
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THEN 

specifies that a single command or a group of commands (introduced by 
DO) are to be executed if the comparison was true. THEN can be followed 
by another IF command. 

ELSE 

specifies that a single command or a group of commands (introduced by 
DO) is to be executed if the previous comparison is false. ELSE can be 
followed by another IF command. 

When an IF command appears in a THEN or ELSE clause, it is called a 
nested IF command. The maximum level of nesting allowed is 10, starting 
with the first time you specify IF. 

Within a nest of IF commands, the innermost ELSE clause is associated with 
the innermost THEN clause, the next innermost ELSE clause with the next 
innermost THEN clause, and so on. (To say it another way, each ELSE is 
matched with the nearest preceding unmatched THEN.) Should there be an 
IF command that does not require an ELSE clause, follow the THEN clause 
with a null ELSE clause (ELSE), unless the nesting structure does not require 
one. 



DO-END Command Sequence 



DO 



specifies that the group of commands that follow is to be treated as a single 
unit, that is, to be executed as a result of a single IF command. The set of 
commands is terminated by END. Commands following a DO must begin 
on a new line. 



END 



specifies the end of a set of commands initiated by the nearest unended 
DO. END must be on a hne by itself. 



Null Commands 



If THEN or ELSE is not followed by a continuation character or by a 
command in the same record, the THEN or ELSE results in no action. 

The null command supports an ELSE command that balances an 
EF-THEN-ELSE command sequence, and allows null THEN commands. The 
null command is, in essence, a THEN or ELSE command that is not followed 
by a command-continuation character. 

If you want to indicate a null ELSE command, specify: 

ELSE 

If you want to indicate a null THEN command, specify: 

IF . . . THEN 
ELSE ... 

The null command is used to indicate that no action is to be taken if the IF 
clause is satisfied (a null THEN command) or if the IF clause is not satisfied 
(a null ELSE command). 
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SET Command 



FARM Command 



The SET command is used to change or reset a previously defined condition 
code. See "Condition Codes" earlier in this chapter for the meaning of 
condition codes. It is possible to terminate all processing simply by setting 
MAXCC or LASTCC to 1 6. 

The format of the SET command is: 



SET 



{MAXCC I laASlCC}{h]=[h]number 



SET 

specifies that a condition-code value is to be set. A SET command that 
follows a THEN or ELSE that is not executed does not cause the value of 
LASTCC or MAXCC to be altered. 

MAXCC 

specifies that the value to be reset is the maximum condition code set by a 
previous functional command. Setting MAXCC does not affect the value 
of LASTCC. 

LASTCC 

specifies that the value to be reset is the condition code set by the 
immediately previous functional command. 

number 
specifies the value to be assigned to MAXCC or LASTCC. The maximum 
value that can be assigned is 16; a greater value will be reduced to 16. If 
the value assigned to LASTCC is greater than the value of MAXCC, 
MAXCC is set equal to the higher value. 



The PARM command specifies processing options to be used during 
execution. These options remain in effect until changed by another PARM 
command. You can also specify these options in the PARM field of an EXEC 
statement (in the JCL). 

The format of the PARM command is: 



PARM 


[1EST( 




{[TRACE] 




[AREAS( areaid [ b areaid ...])] 




[FULL(( dumpid [ b count 1 [ fe count! ]]) 




[{dumpid...Um 1 




OFF} )] 




[GRAFHICS(CHAIN( chain ) | TABLE( mname ))] 




[MARGINS( /^//margm b rightmargin )] 
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where: 

TEST( 

{ [ TRACE ] 

[ AREAS ( areaid [ b areaid ...])] 

[ FULL(( dumpid [ b countl [ b count2 ]] ) 
[ ( dumpid ...)... ] ) ] I 

OFF}) 
specifies the diagnostic aids to be used. Once the TEST option has been 
established, it remains in effect until it is reset by another FARM 
command. The TRACE, AREAS, and FULL parameters may be used 
concurrently. 

TRACE 

specifies that trace tables are to be listed whenever the built-in dump 
points of the processor are encountered. 

AREAS( areaid [ b areaid ... ] ) 

identifies modules that are to have selected variables dumped at their 
dump points. Each item in the areaid is a two-character area-identifier 
defined within the implementation. See 0S/VS2 Access Method 
Services Logic for more information. 

FULL(( dumpid [ b countl [ b countl ]] ) [ dumpid ... ]...]) 

specifies that a region dump, as well as the trace tables and selected 
variables, are to be provided at the specified points, dumpid specifies 
the four-character identifier of the dump point. See 0S/VS2 Access 
Method Services Logic for more information. 

countl 

is a decimal integer that specifies the number of times (default is 1 ) 
the program is to go through the dump point before beginning the 
dump listing. 

count2 

specifies a decimal integer which is the number of times (default is 1) 
through the dump-point that dumps are to be listed. 

If the FULL kejrword is used, an AMSDUMP DD statement must be 
provided. For example: 

//AMSDUMP DD SYSOUT=A 

OFF 

specifies that testing is to stop. 

GRAPfflCS(CHAIN( chain ) \ TABLE( mname )) 

specifies the print chain/train graphic character set or a special graphics 
table to be used in producing the output. Any character to be printed is 
translated to the bit pattern found in such a table at the position 
corresponding to its numeric value (0-255). If the print chain does not 
have a graphic for a byte's bit pattern, the table should specify a period as 
the output graphic. 

CHAIN(AN I HN.I ^ I QN I RN I SN I TN) 

specifies the graphic character set of the print chains or trains you wish 
employed. PN is used by the processor unless explicitly directed to use 
another set of graphics. 
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TABLE( mname ) 

specifies the name of a user-supplied table. This 256-byte table defines 
the graphics for each of the 256 possible bit patterns. It must be stored 
as a module accessible through the LOAD macro (VS). 

MARGINS( leftmargin b rightmargin ) 

specifies that the margins of input records on which command statements 
are written are to be changed. The normal left and right margins are 2 and 
72, respectively. If MARGINS is coded, aU subsequent input records are 
scanned in accord with the new margins. This feature may be used in 
conjunction with the comment feature: respecification of margins could be 
used to cause the /* and */ characters to be omitted from the scan and so 
cause comments to be treated as commands. 

leftmargin 

specifies the location of the left margin. 

rightmargin 

specifies the location of the right margin. The right margin value must 
be greater than the left margin value. 



Control Command Execution Examples 



The examples in the topics that follow show the use of the IF-THEN-ELSE 
command sequence, the SET command, and the FARM command. 



Control Command Execution: Example 1 



In this example, nested IF commands are used to determine whether a 
REPRO, DELETE, or PRINT command is to be executed. 

IF LASTCC > 4 - 

THEN IF MAXCC < 12 - 

THEN REPRO. . . 

ELSE DELETE . . . 
ELSE IF LASTCC = 4 - 

THEN 

ELSE PRINT . . . 

This example specifies that if the value of LASTCC is greater than 4, then the 
value of MAXCC is to be tested. If the value of MAXCC is less than 1 2, the 
REPRO command is executed, while if the value of MAXCC is 12 or greater, 
the DELETE command is executed instead. Again, if the value of LASTCC is 
4 or less, LASTCC is tested for being exactly 4: no action is to be taken in 
this case. If, however, LASTCC is less than 4, the PRINT command is to be 
executed. 
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Control Command Execution: Example 2 



In this example, nested BF commands are used to determine whether a 
REPRO or PRINT command is executed. 

IF LASTCC > 4 - 

THEN IF MAXCC < 12 - 

THEN REPRO . . . 

ELSE 
ELSE IF LASTCC = 4 - 

THEN PRINT ... 

Should the first IF command determine that LASTCC is greater than 4, and 
the second IF command detennine that MAXCC is 12 or greater, no 
functional command in the example is executed. The null ELSE command is 
employed here to specify that the next ELSE is to correspond to the first 
THEN. 



Control Command Execution: Example 3 



In this example, if the maximum condition code is zero, an entry from a 
catalog is listed and a data set is printed. 

IF MAXCC=0 THEN DO 

LISTCAT CATALOG ( AMASTCAT/MST27 ) ENT (MNO 1.0005) 

PRINT INFILE ( AJK006 ) 

END 

ELSE .... 



Control Command Execution: Example 4 

If you want to list a catalog and print a data set if the last condition code is 
zero, but list its catalog entry before and after a VERIFY command if the last 
condition code is greater than zero, specify: 

IF LASTCC = THEN DO 
LISTCAT 

PRINT INFILE (AJK006) 
END 
ELSE DO 

LISTCAT ENTRY (AJK006) ALL 

VERIFY FILE ( AJKJCL6 ) 

LISTCAT ENTRY {AJK006) ALL 

END 

Control Command Execution: Example 5 

If you want to set the last condition code established to 12, specify: 

SET LASTCC=12 

Control Command Execution: Example 6 

If you want to replace the highest condition code established in processing so 
far with 8, specify: 

SET MAXCC=8 
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APPENDIX A: EXAMPLES OF JOBS USING 
ACCESS METHOD SERVICES COMMANDS 



This set of examples is meant to show a wide range of functions provided by 
Access Method Services. It is assumed that the VSAM system catalog that 
exists is recoverable and security protected at the update-, control- and 
master-password levels. 



Example 1: Define a VSAM User Catalog 



Explanation of Commands 



In this example, a user catalog is defined. The catalog is password protected. 
The user catalog in this example is security protected and is not defined with 
the recoverable attribute. The catalog's data space is defined to be 15 
cylinders. The space explicitly specified for the data and index component of 
the catalog is taken from the catalog's data space. Since the total data space 
for the data and index component is less than the total catalog data space, the 
remaining catalog data space is available for suballocation. The volume 
VSER02 cannot be referenced by other VSAM catalogs since it now belongs 
to the catalog which it contains. 

//DEFCAT JOB . . , 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

DEFINE USERCATALOG - 

(NAME{D27UCAT1 ) - 
MASTERPW( UCATMRPW ) - 
UPDATEPW( UCATUPPW ) - 
FOR(365) - 
CYLINDERS (.15 5) - 
VOLUMES (VSERO 2) - 
DATA( - 

CYLINDERS (3 1 ) ) - 
INDEX ( - 

CYLINDERS ( 1 ) ) - 
CATALOG ( AMASTCAT/MCATUPPW ) 
/* 



1 . The USERCATALOG parameter is required and NAME specifies the user 
catalog being defined. 

2. The MASTERPW parameter specifies the master password for this catalog. 

3. The UPDATEPW parameter specifies the update password of this catalog. 

4. The FOR parameter specifies the retention period for this file — in this 
case, one year. 

5. The CYLINDERS parameter specifies the amount of space to be allocated 
to the catalog's data space. A space parameter is required. 

6. The VOLUMES parameter is required and specifies the volume containing 
this catalog. Access Method Services will djmamically allocate the catalog's 
volume; the volume should be mounted permanently RESIDENT or 
RESERVED to ensure successful dynamic allocation. 

7. The DATA parameter specifies the amount of space to be allocated to the 
catalog's data component. 
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8. The INDEX parameter specifies the amount of space to be allocated to the 
catalog's index component, VSAM adds together the amount of space 
specified via DATA and INDEX and determines the appropriate 
proportions for each component. 

9. The CATALOG parameter is required since the master catalog is password 
protected. It specifies the name of the master catalog and its update 
password which is required to define into a protected catalog. 



Example 2: Define a VSAM User Catalog and a VSAM Data 
Space 



Explanation of Commands 



This example defines a user catalog by using the previously-defined user 
catalog, D27UCAT1, as a model. The second part of this example defines a 
VSAM data space on volume VSER04. Both volumes in this example become 
owned by the respective catalogs, D27UCAT2 and AMASTCAT; they 
cannot be referenced by any other VSAM catalogs. 

The third part of this example defines alias names for the user catalogs, 
D27UCAT1 andD27UCAT2. 

This example depends on the successful completion of the previous example 
for the user catalog, D27UCAT1. 

//DEFCAT2 JOB . . . 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

DEFINE USERCATALOG - 

( NAME( D27UCAT2 ) - ■ 

MODEL(D27UCAT1/UCATMRPW D27UCAT1 ) - 

VOLUME! VS EROS) - ( 

CYLINDER! 15 5) ) - 

CATALOG! AMASTCAT/MCATUPPW ) 

DEFINE SPACE - 

( VOLUME! VSER04) - 
CYLINDERS! 10 1) ) - 
CATALOG! AMASTCAT/MCATUPPW ) 

DEFINE ALIAS - 

!NAME!D40) - 
RELATE! D27UCAT1 ) ) — 
CATALOG! AMAS'i'CA'l'/MCATUPPW ) 

DEFINE ALIAS - 

!NAME!D50) - 
RELATE! D27UCAT2 ) ) - 
CATALOG! AMASTCAT/MCATUPPW ) 



The first DEFINE command defines a user catalog on volume VSER03. The 
catalog's attributes are modeled from a previously-defined user catalog, 
D27UCAT1. The VOLUME and CYLINDERS parameters are required 
parameters, even through a model catalog is used. 

L The USERCATALOG parameter is required and NAME specifies the 
name of the tiser catalog, D27UCAT2. 

2. The MODEL parameter names the object to be used as a model and its 
master password, D27UCAT1/UCATMRPW. The next field names the 
catalog that contains the model object's catalog entries. In this case, 
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D27UCATrs self -describing entries describe the object model, 
D27UCAT1. 

3. The VOLUME parameter is required and names the volume that is to 
contain the user catalog. Access Method Services will dynamically allocate 
the catalog's volume; the volume should be mounted permanently 
RESIDENT or RESERVED to ensure successful dynamic allocation. 

4. The CYLINDERS parameter specifies the primary and secondary 
allocation amounts (of cylinders) to be allocated to the catalog's data 
space. A space parameter specifying the total amount of space is required. 
The space is allocated to data and index components of the catalog in the 
same way as that of the model. 

5. The CATALOG parameter is required since the master catalog is password 
protected. It names the master catalog, AMASTCAT, and specifies its 
update password. When a user-catalog is defined, a user catalog connector 
entry is built and written into the VSAM master catalog. The user-catalog 
connector entry enables the user catalog's volume to be located through 
the master catalog. 

The second DEFINE command defines a VSAM data space on volume 
VSER04 and establishes the volume's ownership by the master catalog, 
AMASTCAT. All subsequent VSAM objects created on volume VSER04 are 
required to be cataloged in the volume's catalog, AMASTCAT. 

1 . The SPACE parameter is required. 

2. The VOLUME parameter is required and names the volume that is to 
contain the data space. Access Method Services will dynamically allocate 
the volume; the volume should be mounted permanently RESIDENT or 
RESERVED to ensure successful dynamic allocation. 

3. The CYLINDERS parameter specifies the primary and secondary 
allocation amounts of cyUnders to be allocated to the data space. A space 
parameter is required. 

4. The CATALOG parameter identifies the master catalog, AMASTCAT, 
and supplies its update password. 

The defines of the alias names permit references to the respective user 
catalogs by the alias names. Alias names for VSAM catalogs also provide a 
way by which data set names can be used to direct the search for catalog 
information about data sets. Some of the following examples will show how 
data set naming conventions are used to simplify JCL specification of 
JOBCAT and STEPCAT DD statements. 

1. The ALIAS parameter is required and NAME specifies the alias name of 
the user catalog. 

2. The RELATE parameter specifies the catalog for which the alias is 
defined. 

3. The CATALOG parameter supplies the update password of the master 
catalog, AMASTCAT. 
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j^^fffplg J • j)gyfit£ VSAM Data Ssts 



This example defines four VSAM data sets: two key-sequenced data sets into 
the user catalog, D27UCAT1, a relative-record data set into the system 
catalog, and a reusable entry-sequenced data set into the user catalog, 
D27UCAT2, 

This example depends on the successful completion of Example 1 for the user 
catalog. 

//DEFVSAM JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

DEFINE - 

CLUSTER ( - 

NAME(D40.MYDATA) - 

VOLUMES(VSER02 ) - 

RECORDS! 1000 500) - 
DATA( - 

NAME(D40.KSDATA) - 

KEYS( 15 0)- 

RECORDSIZEC 250 250 ) - 

FREESPACE{ 20 10) - 

BUFFERSPACE( 25000) ) - 
INDEX! - 

NAME (D40.KS INDEX) - 

IMBED ) - 
CATALOG! D27UCAT1 /UCATUPPW ) 

DEFINE CLUSTER - 

( NAME ( D4 . EXAMPLE . KSDS 1 ) - 
READPW(KSDIPSWD) - 
MODEL! D40 . MYDATA ) ) - 
DATA! - 

! NAME ! D4 . EXAMPLE . KSDS 1 . DATA ) - 
UNIQUE - 

CYLINDERS! 2 1))- 
INDEX! - 

! NAME ! D4 . EXAMPLE . KSDS 1 . INDEX ) - 
UNIQUE - 

CYLINDERS! 11))- 
CATALOG! D27UCAT1 /UCATUPPW ) 

IF LASTCC = - 
THEN - 
LISTCAT ENTRIES! - 

D4 0. EXAMPLE. KSDS 1/KSD1PSWD) - 

ALL 

DEFINE CLUSTER - 

! NAME ! EXAMPLE . RRDS 1 ) - 
VOLUMES! VSERO 4) - 
TRACKS! 10 5)- 
RECORDSIZE! 100 100) - 
NUMBERED ) - 
CATALOG! AMASTCAT/MCATUPPW ) 

IF LASTCC = - 
THEN - 
LISTCAT ENTRIES! - 

EXAMPLE . RRDS 1 ) - 
CLUSTER - 
ALL 
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Explanation of Commands 



DEFINE CLUSTER - 

( NAME (D50. EXAMPLE. ESDS1 ) 
MASTERPW(ESDIMRPW) - 
UPDATEPWCESDIUPPW) - 
VOLUMES (VSERO 3) - 
SPANNED - 
REUSE - 
NONINDEXED - 
CYLINDERS! 2 1)- 
RECbRDSIZE( 2500 3000) ) 
CATALOGC D27UCAT2/UCATMRPW )' 

IF LASTCC = - 
THEN - 
LISTCAT ENTRIES ( - 

D50. EXAMPLE. ESDS1 ) - 
ALLOCATION 
/* 



The first DEFINE command defines a key-sequenced data set on volume 
VSER02. The high-level name of the data set is the alias name of the catalog 
into which it is being defined. 

1 . The CLUSTER parameter is required and NAME specifies the cluster 
being defined. 

2. The VOLUMES parameter is required and specifies the volume containing 
the data set. 

3. The RECORDS parameter specifies the space to be allocated to the 
cluster. This is a required parameter. 

4. The DATA parameter is required when attributes are to be expUcitly 
specified for the data component of the cluster. The NAME parameter 
specifies the name of the data component. 

5. The KEYS parameter specifies the key length and offset. 

6. The RECORDSIZE parameter specifies the average and maximum record 
sizes. 

7. The BUFFERSPACE parameter is specified for improved performance. 

8. The INDEX parameter is required when attributes are to be explicitly 
specified for the index component of the cluster. The NAME parameter 
specifies the name of the index component. 

9. The IMBED parameter specifies that the index sequence set is to be placed 
with the data component. 

10. The CATALOG parameter is required since the catalog is password 
protected. 

The second DEFINE command defines a unique key-sequenced data set on 
volume VSER04. The high-level name of the data set is the alias name of the 
catalog into which it is being defined. This example shows how data set 
attributes can be specified by modeling and direct specification. 

L The CLUSTER parameter is required and NAME specifies the cluster 
being defined. 

2. The READPW parameter specifies the read password of this cluster. Since 
no master password is defined, this password will be propagated up to the 
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master level. Thus this cluster is security protected even though its model 
was not protected. 

3. The MODEL parameter specifies the name of the data set to be used as 
the model. 

4. The DATA parameter is required if attributes are to be specified for the 
data component. The NAME parameter specifies the name of the data 
component. If a name is not specified, a name is generated. 

5. The UNIQUE parameter specifies that this portion of the data set is the 
only one that occupies the data space allocated to it. 

6. The CYLINDERS parameter specifies the amount of space to be allocated 
to the cluster's data component. 

7. The INDEX parameter is required if attributes are to be specified for the 
index component. The NAME parameter specifies the name of the index 
component. If a name is not specified, a name is generated. 

8. The UNIQUE parameter specifies that this portion of the data set is the 
only one that occupies the data space allocated to it. 

9. The CYLINDERS parameter specifies the amount of space to be allocated 
to the cluster's index component. 

10. The CATALOG parameter is required, since the user catalog is password 
protected. It specifies the name of the user catalog and its update password 
which is required to define into a protected catalog. 

If the define of the unique key-sequenced data set was successful, then the 
following LISTCAT command is executed. The high-level name of the data 
set wUl direct the LISTCAT to the appropriate user catalog. 

1. The ENTRIES and ALL parameters cause the entire catalog description of 
the data set just defined to be listed. 

The third DEFINE conunand defines a suballocated relative-record data set 
into the VSAM data space on volume VSER04 which is owned by the master 
catalog. 

1. The CLUSTER parameter is required and NAME specifies the cluster 
being defined. 

2. The VOLUMES parametcf is required and specifies the volume containing 
this data set. Because the master catalog is recoverable. Access Method 
Services will dynamically allocate this volume to access the catalog 
recovery area for the data set. This requires that the volume be mounted 
permanently RESIDENT or RESERVED. 

3. The TRACKS parameter specifies the amount of space allocated to this 
data set. A space parameter is required. 

4. The RECORDSIZE parameter specifies the average and maximum record 
sizes which, in the case of a relative-record data set, must be equal. 

5. The NUMBERED' parameter is required to specify that this is a 
relative-record data set. 

6. The CATALOG parameter is required since the master catalog is password 
protected. It specifies the name of the master catalog and its update 
password which is required to define into a protected catalog. 
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If the define of the suballocated relative-record data set was successful, then 
the following LISTCAT command is executed. 

1. The ENTRIES, CLUSTER, and ALL parameters cause the entry just 
defined to be listed, limited, however, to the cluster entry (that is, the data 
component's entry is not listed). 

The fourth DEFINE command defines a suballocated entry-sequenced data 
set on volume VSER03. 

1. The CLUSTER parameter is required and NAME specifies the cluster 
being defined. The high-level nzune of the data set is the alias name of the 
catalog into which it is being defined. 

2. The MASTERPW parameter specifies the master password of this cluster. 

3. The UPDATEPW parameter specifies the update password of this cluster. 

4. The VOLUMES parameter is required and specifies the volume containing 
this data set. 

5. The SPANNED parameter specifies that records may span control interval 
boundaries. 

6. The REUSE parameter specifies that the data set can be reused, that is, 
reloaded without being deleted and redefined. 

7. The NONINDEXED parameter is required to override the default 
(INDEXED). 

8. The CYLINDERS parameter specifies the amount of space to be allocated 
to this data set. A space parameter is required. 

9. The RECORDSIZE parameter specifies the average and maximum record 
sizes. 

10. The CATALOG parameter specifies the name of the catalog into which 
the cluster is to be defined. The catalog's update or higher-level password 
is required. 

If the define of the suballocated entry-sequenced data set was successful, then 
the following LISTCAT command is executed. The high-level name of the 
data set will direct the LISTCAT to the appropriate catalog. 

1 . The ENTRIES and ALLOCATION parameters cause the data set entry 
just defined to be listed, limited, however, to only volume and allocation 
information. 
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£xample 4: Define Non VSAM and VSAM Data Sets 



This example defines a non VSAM data set into a user catalog, a VSAM 
key-sequenced data set into the system catalog, and a VSAM 
entry-sequenced data set into a user catalog. 

//DEFVSM2 JOB 

//JOBCAT DD DSN=D27UCAT2,DISP=SHR 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

DEFINE NONVSAM - 

{ NAME ( EXAMPLE . NONVSAM 1 ) - 
VOLUMES! 231401 ) - 
DEVICETYPES(2314) ) - 
CATALOG ( D27UCAT1 /UCATUPPW ) 

IF LASTCC = - 
THEN - 
LISTCAT NONVSAM - 

ALL - 

CATAL0G(D27UCAT1 ) 

DEFINE CLUSTER - 

{ NAME ( EXAMPLE . KSDS 2 ) ) - 
DATA( - 

NAME ( EXAMPLE . KSDS 2 . DATA ) - 

MASTERPW( DAT2MRPW ) - 

UPDATEPW( DAT2UPPW ) - 

READPW( DAT2RDPW ) - 

RECORDS ( 500 100) - 

EXCEPTIONEXIT( DATEXIT ) . - 

ERASE - 

FREESPACE(20 10) - 

KEYS(6 4) - 

REC0RDSIZE( 80 1 00 ) - 

VOLUMES! VSER04) ) - 
INDEX ( - 

NAME ( EXAMPLE . KSDS 2 . INDEX ) - 

MASTERPW( IND2MRPW ) - 

UPDATEPW( IND2UPPW ) - 

READPW( IND2RDPW ) - 

RECORDS! 300 300) - 

IMBED - 

VOLUMES! VSER04 ) ' ) - 
CATALOG! AMASTCAT/MCATUPPW ) 

IF LASTCC = - 
THEN - 

LISTCAT DATA - 
ALL - 
ENTRIES! - 

EXAMPLE. KSDS 2/DAT2MRPW) - 
CATALOG! AMASTCAT ) 
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DEFINE CLUSTER - 

( NAME( EXAMPLE . ESDS2 ) - 
VOLUMES (VSERO 3) - 
SPANNED - 
CYLINDERS ( 2 1)- 
NONINDEXED - 
REUSE - 

MASTERPW( ESD2MRPW ) - 
CONTROLPW( ESD2CTPW ) - 
UPDATEPW( ESD2UPPW ) - 
READPW( ESD2RDPW ) ) - 
CATALOG( D27UCAT2/UCATMRPW ) 

IF LASTCC = - 
THEN - 
DO - 
LISTCAT ENTRIES( - 

EXAMPLE . ESDS2/ESD2MRPW ) ■ 
ALL 
LISTCAT NAME - 

CATALOG ( AMASTCAT/MCATMRPW ) 
END 

/* 



Explanation of Job Control Language Statements 



Explanation of Commands 



1 . The JOBCAT DD statement describes the user catalog D27UCAT2 as a 
job catalog. All references will be to this job catalog unless otherwise 
directed. 



The first DEFINE command defines an existing nonVSAM data set into user 
catalog D27UC ATI. 

1. The NONVSAM parameter is required and NAME specifies the 
nonVSAM object being defined. 

2. The VOLUMES parameter is required and specifies the volume 
containing the data set. 

3. The DEVICETYPES parameter is required and specifies the device type 
of the volume. 

4. The CATALOG parameter specifying the name of the user catalog is 
required because: 

• a job catalog also appears in the job control language so this parameter 
explicitly directs the define to the user catalog. 

• the catalog is protected and its update password is required for the 
define. 

If the definition of the nonVSAM entry was successful, then the following 
LISTCAT command is executed. 

1. The NONVSAM and ALL parameters cause all the nonVSAM entries 
cataloged in D27UCAT1 to be listed. 

2. The CATALOG parameter directs the LISTCAT to a specific user 
catalog. 
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The second DEFINE command defines a key-sequenced data set into a 
VSAM data space owned by the master catalog. Note that attributes are 
specified at the data and index level rather than the cluster level. Access 
Method Services will dynamically allocate the volume containing the catalog 
recovery area for the cluster, since the system catalog is recoverable. This 
requires that the volume containing the index component of the cluster be 
mounted permanently RESIDENT or RESERVED to ensure successful 
dynamic allocation. 

1. The CLUSTER parameter is required and NAME specifies the cluster 
being defined. 

2. The DATA component is explicitly named via the NAME parameter. 

3. The MASTERPW, UPDATEPW, and READPW parameters specify the 
master, update, and read passwords, respectively, of this data component. 

4. The RECORDS parameter specifies the amount of space to be allocated 
to the data component. A space allocation parameter is required. 

5. The EXCEPTIONEXIT parameter specifies the name of the routine to 
be given control if an exception occurs while processing the data 
component. 

6. The ERASE parameter specifies that the data component is to be 
overwritten with binary zeros when it is deleted. 

7. The FREES? ACE parameter specifies the percentage of space within 
control intervals and control areas, respectively, that is to remain free. 

8. The KEYS parameter specifies the key length and offset. 

9. The RECORDSIZE parameter specifies the average and maximum record 
sizes. 

10. The VOLUMES parameter is required and specifies the volume 
containing this data component. 

11. The INDEX component is explicitly named via the NAME parameter. 

12. The MASTERPW, UPDATEPW, and READPW parameters specify the 
master, update, and read passwords, respectively, of this index 
component. 

13. The RECORDS parameter specifies the amount of space to be allocated 
to the index component. A space allocation parameter is required. 

14. The IMBED parameter specifies that the index sequence set is to be 
placed with the data component. 

15. The VOLUMES parameter is required and specifies the volume 
containing this index component. 

16. The CATALOG parameter is required since the master catalog is 
password protected. It specifies the name of the master catalog and its 
update password which is required to define into a protected catalog. This 
parameter is also required because a DD statement for the job catalog 
(JOBCAT) appears in the job control language and this define must, 
therefore, be explicitly directed to the master catalog. 
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If the definition of the key-sequenced data set was successful, then the 
following LISTCAT command is executed. 

1 . The DATA, ALL, and ENTRIES parameters cause all of the information 
contained in the data component entry to be listed. 

2. The CATALOG parameter directs the LISTCAT to the master catalog. 
The third DEFINE command defines an entry-sequenced data set. 

1 . The CLUSTER parameter is required and NAME specifies the cluster 
being defined. 

2. The VOLUMES parameter specifies the volume (VSER03) which is to 
contain the data set being defined. 

3. The SPANNED parameter specifies that records may span control 
interval boundaries. 

4. The CYLINDERS parameter specifies the amount of space to be 
allocated to this data set. A space parameter is required. 

5. The NONINDEXED parameter is required to override the default 
(INDEXED). 

6. The REUSE parameter specifies that the data set can be reused, that is, 
reloaded without being deleted and redefined. 

7. The MASTERPW, CONTROLPW, UPDATEPW, and READPW 
parameters specify passwords different from the passwords specified for 
the data set being modeled. 

8. The CATALOG parameter is required since the user catalog is password 
protected. 

If the define of the entry-sequenced data set was successful, then the 
following LISTCAT commands are executed. 

1 . The ENTRIES and ALL parameters of the first LISTCAT command 
cause all the cataloged information in the entry just defined to be listed. 

2. The NAME parameter of the second LISTCAT command causes only the 
names of the objects cataloged in the master catalog to be listed. 

3. The CATALOG parameter specifies the master password of the master 
catalog which allows access to all objects in the catalog and directs the 
LISTCAT to the master catalog. 
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Example 5: Copying and Printing 



This example shows various techniques which can be used to load and print 
data sets using the REPRO and PRINT commands. This example depends on 
the successful completion of Examples 3 and 4 for the existence of VSAM 
data sets to load records into. This example also requires that various 
nonVSvXM data sets exist, so that data records can be loaded into the VSAM 
data sets. 

//COPYPRNT JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//* NONVSAM INDEXED-SEQUENTIAL DATA SET 

//INDSET1 DD DSNAME=D40.IF100,DISP=OLD,DCB=DSORG=IS, 

// VOL=SER=231401 ,UNIT=2314 

//* NONVSAM SEQUENTIAL DATA SET (VARIABLE-LENGTH 

//* RECORDS ) 

//INDSET2 DD DSNAME=D40 . SVB200 ,DISP=OLD, 

// VOL=SER=231401,UNIT=2314 

//* NONVSAM SEQUENTIAL DATA SET (FIXED-LENGTH 

//* RECORDS ) 

//INDSET3 DD DSNAME=D40 . SF1 00 , DISP=OLD, 

// VOL=SER=231401 ,UNIT=2314 

//* NONVSAM SEQUENTIAL DATA SET 

//INDSET4 DD DSNAME=EXAMPLE .NONVSAM 1 ,DISP=OLD, 

// VOL=SER=23 1 40 1 , UNIT=23 1 4 

//SYSIN DD * 

/* LOAD A VSAM KEY-SEQUENCED DATA SET */ 
/* FROM AN ISAM DATA SET */ 

REPRO INFILE( INDSET1 ) - 

OUTDATASET( D40 . EXAMPLE . KSDS 1 /KSD1 PSWD ) 

IF MAXCC = - 
THEN - 

PRINT INDATASET(D40. EXAMPLE. KSDS 1/KSD1 PSWD) - 
FROMKEY(X'40F0F0F0F0F6' ) 

/* LOAD A V^AM ENTRY- SEQUENCED DATA SET FROM AN */ 
/* EXISTING VARIABLE UNBLOCKED SAM DATA SET */ 

REPRO INFILE( INDSET2 ) - 

OUTDATASET( D50 . EXAMPLE . ESDS 1 /ESDI UPPW ) - 
COUNT( 030 ) 

IF LASTCC = - 
THEN - 
PRINT INDATASET( D50. EXAMPLE. ESDS 1 ) - 

FROMADDRESS( 170 ) - 

HEX 

/* LOAD A VSAM RELATIVE-RECORD DATA SET FROM AN */ 
/* EXISTING SAM DATA SET */ 

REPRO INFILE( INDSET3 ) - 

OUTDATASET( EXAMPLE . RRDS 1 ) - 
SKIP(IO) 
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IF LASTCC = - 
THEN - 

PRINT INDATASET( EXAMPLE. RRDS 1 ) - 
TONUMBERC 25 ) 

/* PRINT THE CONTENTS OF THE SAM DATA SET */ 

PRINT INFILE( INDSET3 ) - 
COUNT( 20 ) - 
CHARACTER 

/* LOAD A VSAM KEY-SEQUENCED DATA SET */ 
/* FROM A NONVSAM DATA SET */ 

REPRO INFILE( INDSET4 ) - 

OUTDATASET( EXAMPLE . KSDS2 ) 

IF LASTCC = - 
THEN - 

PRINT INDATASET( EXAMPLE. KSDS 2 ) - 
FROMKEY(AAAAJA) - 
T0KEY(AAAAJ9) 
/* 

Explsuiation of Job Control Language Statements 

1. The INDSETl DD statement describes the ISAM data set which is to be 
copied into the VSAM data set D40.EXAMPLE.KSDS1. 

2. The INDSET2 DD statement describes the variable-length SAM data set 
which is to be copied into the VSAM data set D50.EXAMPLE.ESDS1. 

3. The INDSET3 DD statement describes the SAM data set which is to be 
copied into the VSAM data set EXAMPLE.RRDSl. 

4. The INDSET4 DD statement describes the SAM data set which is to be 
copied into the VSAM data set EXAMPLE.KSDS2. 



Explanation of Commands 



The first REPRO command causes a VSAM key-sequenced data set to be 
loaded from an ISAM data set. 

1. The INFILE parameter identifies the data set containing the source data. 
(Note: Either INFILE or INDATASET parameter is required). The dmme 
of the DD statement for this data set must be identical to this name. 

2. The OUTDATASET parameter identifies the name of the data set to be 
loaded. (Note: Either OUTFILE or OUTDATASET parameter is required). 
The data set is dynamically allocated by Access Method Services. The catalog 
containing data set is located by its alias 'D40'. The update or higher 
password of the VSAM data set is required. 

If the REPRO operation was successfully executed, then the contents of the 
VSAM key-sequenced data set just loaded are printed. The format of the 
listing is DUMP, since the default is taken. 

1. The INDATASET parameter identifies the name of the data set to be 
printed, (Note: Either INFILE or INDATASET parameter is required). The 
data set is dynamically allocated by Access Method Services. The catalog 
containing the data set is located by its alias 'D40'. The update- or 
higher-level password of the VSAM data set is required. 

2. The FROMKEY parameter specifies that printing is to begin with the 
record whose key (high-order three bjrtes) is greater than or equal to 
'b 00006' (that is, the character equivalent of X'40F0F0F0F0F6'). 
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The second REPRO command causes a VSAM entry-sequenced data set to 
be loaded from an existing variable unblocked SAM data set. 

1. The INFILE parameter identifies the data set containing the source data. 
The dname of the DD statement for this data set must be identical to this 
name. 

2. The OUTDATASET parameter identifies the name of the data set to be 
loaded. The data set is dynamically allocated by Access Method Services. 
The catalog containing the data set is located by its alias 'D40'. The 
update or higher password of the VSAM data set is required. 

3. The COUNT parameter specifies that the first 30 records of the SAM 
data set are to be loaded. 

If the REPRO operation was successfully executed, then the contents of the 
VSAM entry-sequenced data set just loaded are printed in hexadecimal 
format. 

1. The INDATASET parameter identifies the name of the data set to be 
printed. The data set is dynamically allocated by Access Method Services. 
The catalog containing the data set is located by its alias 'D40'. Since the 
data set is not read protected, no password is required. 

2. The FROMADDRESS parameter specifies that the first record printed is 
that record whose relative byte address is exactly equal to 170. 

3. The HEX parameter specifies that the listing is to be in hexadecimal 
format. 

The third REPRO command causes a VSAM relative-record data set to be 
loaded from an existing fixed SAM data set. The relative-record data set can 
receive only fixed length records that equal its defined record length. 

1. The INFILE parameter identifies the data set containing the source data. 
The dname of the DD statement for this data set must be identical to this 
name. 

2. The OUTDATASET parameter identifies the name of the data set to be 
loaded. The data set is dynamically allocated by Access Method Services. 
The data set is cataloged in the master catalog; therefore, no JOBCAT or 
STEPCAT DD statement is required. 

3. The SKIP parameter specifies that the first 10 records of the SAM data 
set are to be bypassed. 

If the REPRO operation was successfully executed, then the contents of the 
VSAM relative-record data set just loaded are printed. 

1. The INDATASET parameter identifies the name of the data set to be 
printed. The data set is dynamically allocated by Access Method Services. 
The data set is cataloged in the master catalog; therefore, no JOBCAT or 
STEPCAT DD statement is required. Since the data set is not read 
protected, no password is required. 

2. The TONUMBER parameter Umits the output to those relative records 
with relative-record number less than or equal to 25. 

The PRINT command causes the contents of the SAM data set to be printed. 

1. The INFILE parameter identifies the data set to be printed. The dname 
of the DD statement for this data set must be identical to this name. 

2. The COUNT parameter specifies that only 20 records are to be printed. 



436 OS/VS2 Access Method Services 



3. The CHARACTER parameter specifies that the listing is to be in 
character format. 

The last REPRO command causes a VSAM key-sequenced data set to be 
loaded from a nonVSAM data set. 

1. The INFILE parameter identifies the data set containing the source data. 
The dname of the DD statement for this data set must be identical to this 
name. 

2. The OUTDATASET parameter identifies the name of the 

data set to be loaded. The data set is dynamically allocated by Access 
Method Services. The data set is cataloged in the master catalog. Note 
that a password is not required since the cluster component is not 
password protected although its data and index components are. 

If the REPRO operation was successfully executed, then the contents of the 
VSAM key-sequenced data set just loaded are printed. The FROMKEY and 
TOKEY parameters are used to limit the output to a specific range of keys. 

1 . The INDATASET parameter identifies the name of the data set to be 
printed. The data set is dynamically allocated by Access Method Services. 
The data set is cataloged in the master catalog. No password is required, 
because the cluster component is not password protected. 

2. The FROMKEY and TOKEY parameters specify the keys at which 
printing is to begin and end, respectively. 



Example 6: Record Replacement 

This example shows techniques for modifying the contents of VSAM data sets 
using the REPRO command. 

^ This example depends on the successful completion of Example 5 for the 

existence of nonempty VSAM data sets. 

//REPLACE JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//INDSET4 DD DSNAME=EXAMPLE .N0NVSAM2 , DISP=OLD, 

// VOL=SER=23 1401, UNIT=23 1 4 

//SYSIN DD * 

REPRO INFILE ( INDSET4 ) - ' 

OUTDATASET( EXAMPLE. KSDS 2) - 
REPLACE 

IF LASTCC = - 
THEN - 
PRINT INDATASET( EXAMPLE. KSDS2 ) - 

FROMKEY( AAAAJA) - 

TOKEY( AAAAJ9) 

REPRO INDATASET( EXAMPLE. RRDS 1 ) - 

OUTDATASET ( D50 . EXAMPLE . ESDS 1 /ESD 1 UPPW ) - 
REUSE 

IF LASTCC = - 
THEN - 

PRINT. INDATASET( D50. EXAMPLE. ESDS 1 ) 
/* 

Explanation of Job Control Language Statements 

1 . The INDSET4 DD statement describes the nonVSAM data set to be 
I, copied into the VSAM data set EXAMPLE.KSDS2. 
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EjxplEiifitioii of ClonunEnds 



The first REPRO command causes records in the VSAM key-sequenced data 
set to be replaced with input from a nonVSAM data set. 

1. The INFILE parameter identifies the data set containing the source data. 
(Note: Either INFILE or INDATASET is required.) The dname of the 
DD statement for this data set must be identical to this name. 

2. The OUTDATASET parameter identifies the target data set. (Note: 
Either OUTFILE or OUTDATASET is required.) Access Method 
Services wiU dynamically allocate the data set. The data set is cataloged in 
the master catalog; therefore, no JOBCAT or STEPCAT DD statement is 
required. Since the cluster is not password protected, no password is 
required. 

3. The REPLACE parameter causes a record in the output data set having 
the same key as a record in the input data set to be replaced. Records in 
the input data set whose key is not already contained in the output data 
set will be inserted in the output data set. 

If the REPRO operation was successfully executed, then the contents of the 
VSAM key-sequenced data set just changed are printed. 

1. The INDATASET parameter identifies the data set to be printed. (Note: 
Either INFILE or INDATASET is required.) Access Method Services will 
dynamically allocate the data set. The data set is cataloged in the master 
catalog; therefore, no JOBCAT or STEPCAT DD statement is required. 
Since the cluster is not password protected, no password is required. 

2. The FROMKEY and TOKEY parameters specify the keys at which 
printing is to begin and end, respectively. 

The second REPRO command causes the VSAM entry-sequenced data set to 
be loaded from the VSAM relative-record data set. 

1. The INDATASET parameter identifies the source data set. Access 
Method Services will dynamicaUy allocate the data set. The data set is 
cataloged in the master catalog. Since the cluster is unprotected, no 
password is required. 

2. The OUTDATASET parameter identifies the target data set. Access 
Method Services will dynamically allocate the data set. The catalog 
containing the data set is located by its alias 'D50'. The update- or 
higher-level password is required to load the data set. 

3. The REUSE parameter specifies that any records already in the 
entry-sequenced data set output are to be overwritten since the 
entry-sequenced data set was defined with the REUSE attribute. 

If the REPRO operation was successfully executed, then the entire contents 
of the reloaded VSAM entry-sequenced data set are printed. 

• The INDATASET parameter identifies the data set to be printed. Access 
Method Services will dynamically allocate the data set. The catalog 
containing the data set is located by its alias 'D50'. Since no read 
password exists for this data set, no password is required. 



438 OS/VS2 Access Method Services 



Example 7: Alter the Cataloged Attributes of VSAM Data Sets 



Explanation of Commands 



This example shows how the cataloged attributes of two VSAM data sets are 
modified. Each ALTER command is followed by a LISTCAT command, 
which will execute only if its previous ALTER command completed 
successfully. The LISTCAT command prints the updated catalog entry. 

This example depends on the successful completion of Example 3, which 
defined the two VSAM data sets whose attributes are being altered. 

//ALTER JOB ... 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

ALTER - 

D4 . EXAMPLE . KSDS 1 . DATA - 
FREESPACE( 10 10 ) 

IF LASTCC = - 
THEN - 
LISTCAT - 

ENTRIES ( D40 . EXAMPLE . KSDS 1 . DATA/KSD 1 PSWD ) - 
ALL 

ALTER - 

D50. EXAMPLE. ESDS1/ESD1MRPW - 
MASTERPW(ESDIPWMR) - 
CONTROLPW(ESDIPWCT) - 
UPDATEPW(ESDIPWUP) - 
READPW(ESDIPWRD) 

IF LASTCC = - 
THEN - 
LISTCAT - 

ENTRIES ( D50 . EXAMPLE . ESDS 1 /ESD 1 PWMR ) - 
CLUSTER - 
ALL 
/* 



The first ALTER command shows how a data set's space management 
attributes are "tuned" for optimum performance. 

The data component, D40.EXAMPLE.KSDSLDATA, of a key-sequenced 
VSAM data set, D40.EXAMPLE.KSDS1, was defined with 40% free space 
in both control intervals and control areas. Now that data records have been 
loaded into the data set, its free space attributes no longer appear to require 
40% freespace. It is now desirable to have 10% free space in both control 
intervals and control areas. The catalog containing the component to be 
altered is located through its alias 'D40', which is the high-level qualifier of 
the component name. 

• D40.EXAMPLE.KSDSLDATA names the entry whose attributes are to 
be altered with this command. No password is required since the data 
object is not password protected. 

• The FREESPACE parameter respecifies percentages of free space that 
apply to the data component. 
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3 xhe MASTERPW and UPDATEPW parameters specify the master and 
update passwords, respectively, for the alternate index. 

4. The KEYS parameter specifies the length of the alternate key and its 
offset in the base cluster record. 

5. The RECORDSIZE parameter specifies the length of the alternate-index 
record. It must be large enough to contain the prime keys for all 
occurrences of any one alternate key since the alternate index is being 
defined with the NONUNIQUEKEY attribute. 

6. The VOLUMES parameter is required and specifies the volume 
containing the alternate index EXAMPLE.AIX. 

7. The CYLINDERS parameter specifies the amount of space to be 
allocated to the alternate index, A space parameter is required. 

8. The NONUNIQUEKEY parameter specifies that the base cluster can 
contain multiple occurrences of any one alternate key. 

9. The UPGRADE parameter specifies that the alternate index is to reflect 
all changes made to the base cluster records, for example, additions or 
deletions of base cluster records. 

10. The CATALOG parameter is required, since the master catalog is 
password protected. It specifies the name of the master catalog and its 
update password which is required to define into a protected catalog. 

The second DEFINE command defines a path over the alternate index. After 
the alternate index has been built, opening with the path name will cause 
processing of the base cluster via the alternate index. 

1 . The NAME parameter is required and names the object being defined. 

2. The PATHENTRY parameter is required and specifies the name of the 
alternate index over which the path is defined and its master password. 

3. The READPW parameter specifies a read password for the path; it will 
be propagated to master-password level. 

4. The CATALOG parameter is required, since the master catalog is 
password protected. It specifies the name of the master catalog and its 
update password which is required to define into a protected catalog. 

The BLDINDEX command builds an alternate index. The assumption is made 
that enough virtual storage will be available to perform an internal sort. 
However, note that DD statements with the default dnames of IDCUTl and 
IDCUT2 have been provided for two external sort work data sets in the event 
that the assumption is incorrect and an external sort must be performed. 

L The INDATASET parameter identifies the base cluster. Access Method 
Services wiU dynamically allocate the base cluster. The base-cluster's 
cluster entry is not password protected even though its data and index 
components are. 

2. The OUTDATASET parameter identifies the alternate index. Access 
Method Services will dynamically allocate the alternate index. The 
update-or higher-level password of the alternate index is required. 

3. The CATALOG parameter specifies the name of the master catalog. If it 
is necessary for BLDINDEX to use external sort work data sets, they will 
be defined in and deleted from the master catalog. The master password 
will permit these actions. 



442 OS/VS2 Access Method Services 



Example 8: Creating an Alternate Index and Its Path 



This example defines an alternate index over a previously loaded VSAM 
key-sequenced base cluster, defines a path over the alternate index to provide 
a means for processing the base through the alternate index, and builds the 
alternate index. The alternate index, path, and base cluster must all be defined 
in the same catalog, in this case, the master catalog. Since the master catalog 
is recoverable. Access Method Services will dynamically allocate the volume 
containing the base cluster's index component in order to access its recovery 
area. 

This example depends on the successful completion of Examples 4, 5, and 6 
for the existence of the nonempty VSAM base cluster EXAMPLE.KSDS2. 

//MAKEAIX JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//IDCUT1 DD DSNAME=SORT. WORK. ONE, DISP=OLD, 

// AMP= • AMORG ' , VOL=SER=VSER0 1 , UNIT=23 1 4 

//IDCUT2 DD DSNAME=SORT.WORK.TWO,DISP=OLD, 

// AMP= ' AMORG ' , VOL=SER=VSER0 1 , UNIT=23 1 4 

//SYSIN DD * 

DEFINE ALTERNATEINDEX - 

( NAME { EXAMPLE. AIX) - 
RELATE ( EXAMPLE . KSDS 2 ) - 
MASTERPW( AIXMRPW ) - 
UPDATEPW( AIXUPPW ) - 
KEYS(3 0) - 
RECORDSIZEC 40 50 ) - 
VOLUMES(VSER04) - 
CYLINDERS (2 1 ) - 
NONUNIQUEKEY - 
UPGRADE ) - 
CATALOG( AMASTCAT/MCATUPPW ) 

DEFINE PATH - 

(NAME (EXAMPLE. PATH) - 
PATHENTRY( EXAMPLE . AIX/AIXMRPW ) - 
READPW( PATHRDPW ) ) - 
CATALOG ( AMASTCAT/MCATUPPW ) 

BLDINDEX INDATASET( EXAMPLE. KSDS2 ) - 

OUTDATASET( EXAMPLE . AIX/AIXUPPW ) - 
CATALOG ( AMASTCAT/MCATMRPW ) 

PRINT INDATASET ( EXAMPLE . PATH/PATHRDPW ) 
/* 



Explanation of Job Control Language Statements 



Explanation of Commands 



The IDCUTl and IDCUT2 DD statements describe the dsnames and a 
volume containing VSAM data space to be made available to 
BLDINDEX for defining and using two sort work data sets in the event 
an external sort is performed. This data space will not be used by 
BLDINDEX if enough virtual storage is available to perform an internal 
sort. 



The first DEFINE conmiand creates a VSAM alternate index over the base 
cluster EXAMPLE.KSDS2. 

1 . The NAME parameter is required and names the object being defined. 

2. The RELATE parameter is required and specifies the name of the base 
cluster over which the alternate index is defined. 
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Expianation of Job Control Language Statements 



Explanation of Commands 



1. The RECEIVE DD statements describe the portable data sets. The 
record fonnat (VBS) and logical record length are set by EXPORT. The 
b|ocksize is set by EXPORT as 2048 except where overridden as in 
STEPl. 



The first EXPORT command causes a key-sequenced VSAM data set to be 
exported from a user catalog. When it has been exported to a magnetic tape 
file, the key-sequenced data set is deleted from the user catalog. 

Note: When an object is exported, the record format of its records on the 
portable file are "VBS," and the EXPORT process determines the 
appropriate record size. However, the RECEIVE DD statement specifies a 
blocksize (BLKSIZE=6000) to override the blocksize used by the EXPORT 
process (2048 bjrtes) and to improve performance. 

1. D40.EXAMPLE.KSDS1 names the key-sequenced VSAM data set being 
exported. Its password, KSDIPSWD, is also supplied (when the data set 

. was defined, its read password propagated upward and all passwords for 
the data set are KSDIPSWD). Access Method Services wiU dynamically 
allocate the cluster. The catalog containing the cluster is located through 
its alias 'D40', which is the high-level qualifier of the cluster name. 

2. The PURGE parameter is required, because the data set was defined with 
a retention period of 365 days. The data set cannot be exported 
permanently (that is, deleted from the catalog after its copy is made in the 
portable file) unless the PURGE parameter is specified to override its 
cataloged retention period. 

3. The OUTFILE parameter names the DD statement that describes and 
allocates the first file on a magnetic tape reel. (Note: Either OUTFILE or 
OUTDATASET is required.) 

The second EXPORT command causes an entry-sequenced VSAM data set 
to be exported from a user catalog. When it has been exported to a magnetic 
tape fOe, the data set's entry in the user catalog is marked "temporary export" 
and "inhibit update," which prevents the data set from being modified in any 
way. The user's program can only read the data set's records. In addition, 
when the data set's copy on magnetic tape is imported into another system 
catalog, the data set's entry in the new, or "target," catalog is marked "inhibit 
update." 

1. D50.EXAMPLE.ESDS1 names the entry-sequenced data set being 
exported. Its master password, ESDIPWMR, is also supplied. (Example 7 
shows how the data set's passwords were changed.) Access Method 
Services will dynamically allocate the cluster. The catalog containing the 
cluster is located through its alias 'D50', which is the high-level qualifier 
of the cluster name. 

2. The OUTFILE parameter names the DD statement that describes and 
allocates the second file on a magnetic tape reel. 

3. The TEMPORARY parameter specifies that the data set is not to be 
deleted from the catalog when it is exported. 

4. The INHIBITSOURCE parameter specifies that the data set that remains 
in the "source" catalog and system is not to be updated or modified. 
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The PRINT command causes the base cluster to be printed by means of the 
alternate key using the path defined to create this relationship. 

• The INDATASET parameter identifies the path object. Access Method ' 
Services will dynamically allocate the path. The read password of the path 
is required. 



Example 9: Exporting VSAM Data Sets 



This example shows various methods of exporting data sets to provide backup 
and portabiUty. 

The example depends on the successful completion of previous examples for 
the existance of the various objects to be exported. 

//EXPORT JOB . . . 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//RECEIVE DD DSNAME=PORTABLE . TAPE 1 , LABEL={ 1 , SL) , 

// UNIT=2400-3,DISP=( NEW, PASS ) , VOL=SER=TAPE01 , 

// DCB=( DEN=3 , BLKSIZE=6000 ) 

//SYSIN DD * 

EXPORT - 

D40. EXAMPLE. KSDS1/KSD1PSWD - 
PURGE - 
OUTFILE( RECEIVE ) 

//STEP2 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A, 

//RECEIVE DD DSNAME=PORTABLE . TAPE2 , LABEL=( 2 , SL) , 

// UNIT=2400-3, DISP=( NEW, PASS ),VOL=SER=TAPE01 , 

// DCB=DEN=3 

//SYSIN DD * 

EXPORT - 

D50. EXAMPLE. ESDS1/ESD1PWMR - 
OUTF I LE( RECEIVE) - 
TEMPORARY - 
INHIBITSOURCE - 
INHIBITTARGET 

//STEP3 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//RECEIVE DD DSNAME=PORTABLE . TAPE3 , LABEL=( 3 , SL ) , 

// DI SP=( NEW, PASS ),VOL=SER=TAPE01 ,UNIT=2400-3 , 

// DCB=DEN=3 

//SYSIN DD * 

EXPORT - 

EXAMPLE. AIX/MCATMRPW - 
OUTF I LE( RECEIVE) 

//STEP4 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//RECEIVE DD DSNAME=PORTABLE . TAPE4 , LABEL=( 4 , SL ) , 

// DISP=( NEW, PASS ),VOL=SER=TAPE01 ,UNIT=2400-3 , 

// DCB=DEN=3 

//SYSIN DD * 

EXPORT - 

EXAMPLE. KSDS2/MCATMRPW - 
OUTFILE( RECEIVE) 
/* 
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Example 10: Importing VSAM Data Sets 

This example shows various methods of importing data sets. 

This example depends on the successful completion of Example 9, which 
created a portable magnetic tape that contains a copy of each VSAM data set 
to be imported. 

//IMPORT JOB . . . ' 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SOURCE DD DSNAME=PORTABLE . TAPE4 , LABEL= ( 4 , SL) , 

// DISP=( OLD , PASS ) , VOL=SER=TAPE0 1 , UNIT=2400-3 , DCB=DEN=3 

//SYSIN DD * 

IMPORT - 

INFILE( SOURCE ) - 
OUTDATASET( EXAMPLE. KSDS 2) - 
CATALOG ( AMASTCAT/MCATUPPW ) - 

//STEP 2 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SOURCE DD DSNAME=PORTABLE . TAPE3 , LABEL=( 3 , SL ) , 

// DI SP={ OLD, PASS ),VOL=SER=TAPE01 ,UNIT=2400-3 ,DCB=DEN=3 

//SYSIN DD * 

IMPORT - 

INFILE( SOURCE ) - 
OUTDATASET( EXAMPLE. AIX) - 
CATALOG ( AMASTCAT/MCATUPPW ) 

//STEP3 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SOURCE DD DSNAME=PORTABLE . TAPE2 , LABEL=( 2 , SL ) , 

// UNIT=2400-3,DISP=( OLD, PASS ),VOL=SER=TAPE01 , 

// DCB= ( DEN= 3 , LRECL= 3004) 

//RECEIVE DD DSN=D50. EXAMPLE. ESDSr,DISP=OLD 

//SYSIN DD * 

IMPORT - 

INFILE( SOURCE) - 
OUTFILE( RECEIVE) - 
CATALOG( D27UCAT2/UCATMRPW ) 

//STEP4 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 

//SOURCE DD DSNAME=PORTABLE . TAPE 1 , LABEL=( 1 , SL ) , 
// UNIT=2400-3 , DISP=( OLD , PASS ) , VOL=SER=TAPE0 1 , 
// DCB=( DEN=3 , LxRECL=479 , ELKSIZE=6000 ) 
V/SYSIN DD * 

IMPORT - 

INFILE( SOURCE ) - 

OUTDATASET(D50.EXAMNEW.KSDS1 ) - 
CATALOG! D27UCAT2/UCATUPPW) - 
OBJECTS ( - 

(D40. EXAMPLE. KSDS 1 - 
VOLUMES( VSER03 ) - 
NEWNAME(D50.EXAMNEW.KSDS1 ) ) - 
( D40. EXAMPLE. KSDS 1 .DATA - 

NEWNAME( D50 . EXAMNEW . KSDS 1 . DATA ) ) - 
( D4 . EXAMPLE . KSDS 1 . INDEX - 
NEWNAMEC D50. EXAMNEW. KSDS 1 .INDEX) ) ) 
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5. The INHIBITTARGET parameter specifies that the data set's exported 
copy is not to be updated or modified when it has been imported into the 
"target" catalog and system. 

The third and fourth EXPORT commands cause the alternate index and base 
cluster to be exported from the master catalog. Any paths defined over either 
object will be exported with their PATHENTRY object. Since the export is 
permanent, both the base cluster and alternate index will be deleted from the 
catalog. The alternate index must be exported first, because the delete of the 
base cluster will cause deletion of all objects defined over it. 

The third EXPORT command causes an alternate index to be exported from 
the master catalog. 

1. The name of the alternate index being exported is required. A master 
password is required for the deletion and to allow VSAM locates against 
both the alternate index and path to obtain the catalog information 
(including passwords) to be exported. The master password of the catalog 
covers all requirements. Access Method Services will dynamically allocate 
the alternate index; this will also provide access to the catalog recovery 
area. 

2. The OUTFILE parameter names the DD statement that describes and 
allocates the third file on a magnetic tape reel. 

The fourth EXPORT command causes a base cluster to be exported from the 
master catalog. 

1. The name of the base cluster being exported is required. Since the cluster 
level is not protected, no password would be required for the deletion. 
However, a password is required for the VSAM locates against the data 
and index components to obtain the catalog information (including 
passwords) to be exported. Since only one password can be supplied, it 
must be that of the master catalog. Access Method Services will 
dynamically allocate the cluster; this will also provide access to the 
catalog recovery area. 

2. The OUTFILE parameter names the DD statement that describes and 
allocates the fourth file on a magnetic tape reel. 
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using the catalog infonnation obtained from the portable data set. Because 
the data set was exported with the TEMPORARY attribute (see the previous 
example), the IMPORT command doesn't need to supply volume information. 

Note: The SOURCE DD statement specifies a recordsize (LRECL=3004) 
because the largest record in the portable data set is 3000 bjftes (that is, 
LRECL = (largest-record size) + 4). Otherwise, the default record size, 
blocksize minus 4, would be erroneously used by the EXPORT command. In 
the two previous steps, the default record size was used. 

1. The INFILE parameter names the DD statement that describes and 
allocates the third file on a magnetic tape reel. This is the portable data 
set to be imported. 

2. The OUTFILE parameter names the DD statement that describes and 
allocates the data set to be imported. Note that since the data set was 
exported with the TEMPORARY attribute, it exists in the catalog 
D27UCAT2 at step allocation time. 

3. The CATALOG parameter is required, since the catalog is protected. It 
names the catalog that is to contain the imported data set. The catalog's 
master password is suppMed, and allows the IMPORT process to delete 
the existing entry in the catalog and redefine a new entry for the 
entry-sequenced VSAM data set. 

The fourth IMPORT command causes the previously-exported key-sequenced 
VSAM data set, D40.EXAMPLE.KSDS1, to be imported from its copy (that 
is, the first portable data set on the magnetic tape reel) to a different user 
catalog than it was exported from, D27UCAT2. The IMPORT command 
renames the data set and each of its components, as specified with the 
NEWNAME parameters, and specifies that the data set is to reside on a 
different volume than that from which it was exported. The high-level 
qualifier (D50) of the new component's name is the aUas name of the user 
catalog, D27UCAT2. 

Note: The SOURCE DD statement describes the portable data set created in 
STEPl of the previous example. The blocksize parameter is included (even 
though it need not be, because the tape has a standard label and the 
information is contained in the data set header label) to illustrate the fact that 
the information specified when the data set is imported is required to be the 
same as was specified when the data set was exported. The LRECL 
parameter is not required, because the maximum record size is 475 bytes and 
the default (blocksize minus 4) is adequate. However, by specifying a record 
size, the default is overridden and virtual storage is more efficiently used. 
When record size is specified, it is the largest-record size + 4. 

1 . The INFILE parameter names the DD statement that describes and 
allocates the portable data set containing the to-be-imported VSAM data 
set. 

2. The OUTDATASET parameter identifies the renamed data set. Access 
Method Services dynamically allocates the data set after it has been 
defined. 

3. The CATALOG parameter is required since the catalog is protected. It 
names the catalog that is to contain the imported data set's entry. The 
catalog's update password is supplied and allows the data set to be 
imported into the catalog. 
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Explanation of Job Control Language Statements 



Explanation of Commands 



The SOURCE DD statements describe the portable data sets. For 
standard labeled tapes, the DCB parameters of LRECL and BLKSIZE 
need not be specified. However, the example shows parameters which 
would be required for a nonlabeled tape. Unless overridden by DCB 
parameters, the EXPORT command sets the blocksize to 2048 and the 
record length to blocksize minus 4. 

The RECEIVE DD statement in STEP3 describes and allocates 
D50.EXAMPLE.ESDS1, which was exported with the TEMPORARY 
attribute. 



The first and second IMPORT commands wiU import the base cluster and 
alternate index exported in Example 9 into the master catalog. The 
importation causes each component to be newly defined. Since the alternate 
index cannot be defined until the base cluster has been defined, the base 
cluster must be imported first. The importation will cause any paths over the 
objects which were exported to be redefined. 

The first IMPORT command causes the base cluster to be imported into the 
master catalog. 

1. The INFILE parameter names the DD statement that describes and 
allocates the fourth file on the magnetic tape reel containing the portable 
data set. (Note: Either INFILE or INDATASET is required.) 

2. The OUTDATASET parameter identifies the data set being imported. 
(Note: Either OUTFILE or OUTDATASET is required.) Access Method 
Services dynamically allocates the data set after it has been defined; this 
wiU also provide access to the catalog recovery area. 

3. The CATALOG parameter is required, since the master catalog is 
password protected. It specifies the name of the master catalog and its 
update password which is required to define into a protected catalog. 

The second IMPORT command causes an alternate index to be imported into 
the master catalog. 

L The INFILE parameter names the DD statement that describes and 
allocates the third file on the magnetic tape reel containing the portable 
data set. 

2. The OUTDATASET parameter identifies the data set being imported. 
Access Method Services dynamically allocates the alternate index after it 
has been defined; this will also provide access to the catalog recovery 
area. 

3. The CATALOG parameter is required, since the master catalog is 
password protected. It specifies the name of the master catalog and its 
update password which is required to define into a protected catalog. 

The third IMPORT command causes the previously-exported 
entry-sequenced VSAM data set to be imported. The data set is imported into 
the catalog from which it was exported. The portable data set (that is, the 
copy being imported) replaces the copy that exists in user catalog 
D27UCAT2. The IMPORT process searches user catalog D27UCAT2 
(located through its alias 'D50') for the entry with an entryname of 
D50.EXAMPLE.ESDSL It deletes that entry, then redefines a cluster entry 
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Explanation of Commands 



/* DELETE THE VSAM USER CATALOG D27UCAT2 

DELETE D27UCAT2/UCATMRPW - 
USERCATALOG - 
PURGE 
/* 



The first DELETE command deletes the nonVSAJM data set named 
EXAMPLE.NONVSAMl . 

1 . The name of the nonVSAM data set is required. 

2. The NOSCRATCH parameter specifies that the VTOC entry of the 
object being deleted is not to be removed. 

3. The NONVSAM parameter ensures that the entry being deleted is a 
nonVSAM data set. 

4. The CATALOG parameter is required in this example to identify the 
catalog that describes the data set to be deleted. The catalog's update 
password is required to delete a nonVSAM data set. 

The second DELETE command deletes VSAM data sets cataloged in two 
user catalogs, D27UCAT1 and D27UCAT2. 

1. The names of the VSAM data sets are specified; in addition the master 
passwords of two protected data sets are required. Since the high-level 
qualifier of the three data set names is the ahas of the catalog that 
describes the data sets, the CATALOG parameter is not required to 
direct the catalog search. 

2. The PURGE parameter causes the entries to be deleted without regard 
for the retention period. 

3. The CLUSTER parameter ensures that the catalog object being deleted is 
a VSAM data set. 

The third DELETE command deletes the entry-sequenced VSAM data set 
EXAMPLE.ESDS2 from the user catalog, D27UCAT2. 

1. The name of the entry-sequenced data set, EXAMPLE.ESD2, and its 
master password, ESD2MRPW, are required to identify the object to be 

2. The PURGE parameter causes the entry to be deleted without regard to 
its retention period. 

3. The CATALOG parameter is required in this example to identify the 
catalog that describes the data set to be deleted. 

The fourth DELETE command deletes the key-sequenced VSAM data set 
EXAMPLE.KSDS2 from the master catalog. Because this data set is a base 
cluster, its related alternate index, EXAMPLE.AIX, and its path, 
EXAMPLE.PATH, are also automatically deleted from the master catalog. 

1. The name of the key-sequenced VSAM data set, EXAMPLE.KSDS2, is 
required to identify the object to be deleted. 

2. The CATALOG parameter is required, because the delete process will 
result in more than one protected object being deleted. It names the 
catalog that contains the catalog entry of each object to be deleted and 
supplies the catalog's master password, which allows each object in the 
catalog to be deleted. 
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The OBJECTS parameter identifies the volume that is to contain the 
imported data set and specifies new names for each of the data set's 
components. The OBJECTS parameter identifies each entry of the 
imported data set with its original entryname, then specifies information 
that is to replace the information found in the portable data set's 
imported catalog entries. 



Example 11: Deleting a VSAM Catalog and Its Cataloged Objects 



This example deletes all entries defined in the previous examples and deletes 
the user catalogs which were defined. The result of this job is the removal of 
all data sets and catalogs defined in this set of examples. 

//DELETE JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

/* DELETE THE NONVSAM DATA SET EXAMPLE. N0NVSAM1 */ 

DELETE EXAMPLE. NONVSAM 1 - 
NOSCRATCH - 
NONVSAM - 
CATALOG ( D27UCAT1 /UCATUPPW ) 

/* DELETE VSAM DATA SETS CATALOGED IN */ 
/* USER CATALOGS D27UCAT1 AND D27UCAT2 */ 

DELETE (D50. EXAMPLE. ESDS1/ESD1PWMR - 
D50.EXAMNEW.KSDSVKSD1PSWD - 
D40.MYDATA) - 
PURGE - 
CLUSTER 

/* DELETE THE ENTRY- SEQUENCED VSAM */ 
^ /* DATA SET EXAMPLE. ESDS2 */ 

-" DELETE EXAMPLE. ESDS2/ESD2MRPW - 

PURGE - 
CATALOG(D27UCAT2) 

/* DELETE THE KEY-SEQUENCED VSAM */ 
/* CLUSTER EXAMPLE. KSDS2 */ 

DELETE EXAMPLE. KSDS 2 - 

CATALOG ( AMASTCAT/MCATMRPW ) 

/* DELETE THE RELATIVE-RECORD VSAM */ 
/* CLUSTER EXAMPLE . RRDS 1 */ 

DELETE EXAMPLE . RRDS 1 - 
CLUSTER 

/* DELETE VSAM DATA SPACES FROM VOLUME */ 
/* VSER04 AND, IF THE VOLUME DOESN'T */ 
/* CONTAIN VSAM OBJECTS, DELETE THE */ 
/* VOLUME'S ENTRY IN AMASTCAT */ 

DELETE VSER04 - 
SPACE - 
CATALOG ( AMASTCAT/MCATUPPW ) 

/* DELETE THE VSAM USER CATALOG D27UCAT1 */ 

DELETE D27UCAT1/UCATMRPW - 
USERCATALOG - 
PURGE 
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Alias Entry Keywords 

ASSOCIATIONS (ASN) 
entryname (HIS) 
HISTORY (HIS) 

RCVY-CI (HIS) 

RCVY-DEVT (HIS) 

RCVY-VOL (HIS) 

RELEASE (HIS) 

Alternate-Index Entry Keywords 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
ATTRIBUTES (ATT) 
CLUSTER (ASN) 
CODE (PRT) 
CONTROLPW (PRT) 
DATA (ASN) 
entryname (HIS) 
HISTORY (HIS) 

CREATION (HIS) 

EXPIRATION (HIS) 

OWNER-IDENT(HIS) 

RCVY-CI (HIS) 

RCVY-DEVT (HIS) 

RCVY-VOL (HIS) 

RELEASE (HIS) 
INDEX (ASN) 
MASTERPW (PRT) 
NOUPGRADE (ATT) 
PATH (ASN) 
PROTECTION (PRT) 
RACE (PRT) 
READPW (PRT) 
UPDATEPW (PRT) 
UPGRADE (ATT) 
USAR (PRT) 
USVR (PRT) 

Cluster Entry Keywords 

AIX (ASN) 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
CODE (PRT) 
CONTROLPW (PRT) 
DATA (ASN) 



entryname (HIS) 

HISTORY. (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 

INDEX (ASN) 

MASTERPW (PRT) 

PATH (ASN) 

PROTECTION (PRT) 

RACE (PRT) 

READPW (PRT) 

UPDATEPW (PRT) 

USAR (PRT) 

USVR (PRT) 

Data Entry Keywords 

ALLOCATION (ALC) 
AIX (ASN) 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
ATTRIBUTES (ATT) 
AVGLRECL (ATT) 
AXRKP (ATT) 
BIND (ATT) 
BUFSPACE (ATT) 
BYTES/TRACK (VLS) 
CI/CA (ATT) 
CISIZE (ATT) 
CLUSTER (ASN) 
CODE (PRT) 
CONTROLPW (PRT) 
CYLFAULT (ATT) 
DEVTYPE (VLS) 
DSTGWAIT (ATT) 
entryname (HIS) 
ERASE (ATT) 
EXCPEXIT (ATT) 
EXCPS (ST A) 
EXTENT-NUMBER (VLS) 
EXTENT-TYPE (VLS) 
EXTENTS (STA) 



EXTENTS (VLS) 

HIGH-CCHH (VLS) 
HIGH-RBA (VLS) 
LOW-CCHH (VLS) 
LOW-RBA (VLS) 
TRACKS (VLS) 
FREESPACE-%CI (STA) 
FREESPACE-%CA (STA) 
FREESPC-BYTES (STA) 
HIGH-KEY (VLS) 
HI-KEY-RBA (VLS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
IMBED (ATT) 
INDEX (ASN) 
INH-UPDATE (ATT) 
INDEXED (ATT) 
KEYLEN (ATT) 
LOW-KEY (VLS) 
MASTERPW (PRT) 
MAXLRECL (ATT) 
MAXRECS (ATT) 
NOERASE (ATT) 
NOIMBED (ATT) 
NONINDEXED (ATT) 
NOREPLICAT (ATT) 
NOREUSE (ATT) 
NONSPANNED (ATT) 
NOSWAP (ATT) 
NOTRKOVFL (ATT) 
NONUNIQKEY (ATT) 
NOTUSABLE (ATT) 
NOWRITECHK (ATT) 
NUMBERED (ATT) 
ORDERED (ATT) 
PGSPC (ASN) 
PHYRECS/TRK (VLS) 
PHYREC/SIZE (VLS) 
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The fifth DELETE command deletes the relative-record VSAM data set 
EXAMPLE.RRDS I from the master catalog. 

1 . The name of the relative-record VSAM data set, EXAMPLE.RRDS 1 , is 
required to identify the object to be deleted. Because the data set was 
created without passwords, no password is required to delete it. 

2. The CLUSTER parameter specifies that a cluster is being deleted. 

The sixth DELETE conmiand deletes each empty VSAM data space from 
volume VSER04. Because the volume no longercontains any VSAM objects, 
the DELETE command also removes the volume's entry from the master 
catalog and removes the master catalog's ownership of the volume. Access 
Method Services will dynamically allocate the volume, since the VTOC must 
be accessed. The volume should be mounted permanently RESIDENT or 
RESERVED to assure successful dynamic allocation. 

Note: If VSAM data sets remain on a volume, the DELETE SPACE 
conmiand only frees unused VSAM space on the volume. 

1. The name (that is, volume serial number) of the volume, VSER04, is 
required to identify the object to be deleted. 

2. The SPACE parameter is required to specify that all data spaces on the 
volume are to be deleted and, if the volume does not contain VSAM 
objects, that the volume's entry is to be deleted from the catalog. 

3. The CATALOG, parameter is required and names the catalog that owns 
the volume. The catalog's update password, MCATUPPW, allows the 
DELETE command to delete a volume entry or VSAM data space. 

The seventh DELETE command deletes the VSAM user catalog 
D27UCATL 

1 . The name of the catalog and its master password are required to identify 
the object to be deleted. 

2. The USERCATALOG parameter is required to specify that a user 
catalog is being deleted. 

3. The PURGE parameter causes the entry to be deleted without regard to 
its retention period. 

The eighth DELETE command deletes the VSAM user catalog D27UCAT2. 

1 . The name of the user catalog and its master password are required. 

2. The USERCATALOG parameter is required to specify that the object 
being deleted is a user catalog. 

3. The PURGE parameter causes the entry to be deleted without regard for 
the retention period. 
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Descnption of Keyword Fields 



ALC: Allocation Group 



ASN: Associations Group 



This section of tlie appendix contains a description of each field name. The 
field names are in the following groups of related information: 

Abbreviations Group Names 

ALC Allocation Group 

ASN Associations Group 

ATT Attributes Group 

DSP Data Space Group 

GDG Generation Data Group Base Entry, Special Fields for 

NVS NonVSAM Entry, Special Field for 

HIS History Group 

PRT Protection Group 

STA Statistics Group 

VLS Volumes Group 

VOL Volume Entry, Special Fields for 

Groups are in alphabetic order. Field names within each group are in 
alphabetic order, not the order of appearance in the listed entry. 



The fields in this group describe the space allocated to the data or index 
component defined by the entry. 



HI-ALLOC-RBA - 

space to store data. 



The highest RBA (plus 1) available within allocated 



HI-USED-RBA — The highest RBA (plus 1) within allocated space that 
actually contains data. 

SPACE-PRI — Gives the number of units (indicated under TYPE) of 
space allocated to the data or index component when the cluster (that is, 
its data or index component) was defined. This amount of space is to be 
allocated whenever a data component (or key range within it, and its 
associated sequence set, if IMBED is an attribute of the cluster) is 
extended onto a candidate volume. 

SPACE-SEC — Gives the number of units (indicated under TYPE) of 
space to be allocated whenever a data set (or key range within it) is 
extended on the same volume. 

SPACE-TYPE — Indicates the unit of space allocation: 

CYLINDER— Cylinders 

. TRACK— Tracks 



This group lists the type (cluster, data, etc.) and entry names of the objects 
associated with the present entry. A cluster or alternate index entry will 
indicate its associated path entries and data and index (if a key-sequenced 
data set) entries. Similarly, an index or data entry will indicate its associated 
cluster or the alternate index of which it is a component. 

• An aUas entry points to: 
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APPENDIX B: INTERPRETING LISTCAT OUTPUT 
LISTINGS 



The various LISTCAT command options allow you to select the LISTCAT 
output that gives you the information you want. This appendix provides 
information on the structure of LISTCAT output when you specify certain 
options. It also lists and describes fields that can be printed for each type of 
catalog entry. 

Each listed entry is identified by its type (that is, cluster, nonVSAM, data, 
etc.) and by its entryname. Entries are listed in alphabetic order of the 
entrynames, except when the ENTRIES parameter is used. The entries are 
then listed in the order in which they are specified in the ENTRIES 
parameter. 

An entry which has associated entries is immediately followed by the listing of 
each associated entry, unless type options (CLUSTER, DATA, SPACE, etc.) 
have been specified or a generic entryname list was specified which excludes 
the associated entry. That is, a cluster's data component (and, if the cluster is 
key-sequenced, its index component) is listed immediately following the 
cluster. 

This appendix is organized in three parts: 

• "LISTCAT Output Keywords," which lists aU field names that can be 
listed for each type of entry. 

• "Description of Keyword Fields," which describes each field name within a 
group of related field names. 

• "Examples of LISTCAT Output Listings," which describes and illustrates 
the LISTCAT output that results when various LISTCAT options are 
specified. 



LISTCAT Output Keywords 



This section of the appendix lists the field names associated with each type of 
catalog entry. Each field name is followed by an abbreviation that points to a 
group of related-field descriptions in the next section. Ke5rwords are listed in 
alphabetic order, not in the order of appearance in the LISTCAT output. 

The group names and abbreviations are: 

Abbreviations Group Names 

ALC Allocation Group 

ASN Associations Group 

ATT Attributes Group 

DSP Data Space Group 

GDG Generation Data Group Base Entry, Special Fields for 

NVS NonVSAM Entry, Special Field for 

HIS History Group 

PRT Protection Group 

STA - Statistics Group 

VLS Volumes Group 



f VOL Volume Entry, Special Fields for 
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DSP: Data Space Group 



REUSE — The data set can be reused (that is, its contents are temporary and 
its high-used RBA can be reset to when it is opened). 

RKP — The relative key position — the displacement from the beginning of a 
data record to its key field. 

SHROPTNS — (n,m) The numbers n and m identify the types of sharing 
permitted. See SHAREOPTIONS in the DEFINE CLUSTER section for 
more details. 

SPANNED — Data records can be longer than control-interval length, and 
can cross, or span, control-interval boundaries. 

SPEED — CLOSE is not issued until the data set has been loaded. 

SUB ALLOC — More than one VSAM cluster can share the data space. A 
VSAM catalog might also occupy the data space. 

SWAP — The page space is a high speed swap data set used by Auxiliary 
Storage Management during a swap operation to store and retrieve the set of 
LSQA pages owned by an address space. 

TEMP-EXP — The data component was temporarily exported. 

TRKOVFL — The physical blocks of a page space data set can span a track 
boundary. 

UNIQUE — Only one VSAM cluster or catalog can occupy the data 
space — the cluster or catalog is unique. 

UNIQUEKEY — Indicates, for an alternate index, that the alternate-key 
value identifies one, and only one, data record in the base cluster. 

UNORDERED — Volumes specified when the cluster was defined can be 
used for space allocation in any order. 

UPDATE — When the path is opened, the upgrade set's alternate indexes 
(associated with the path's base cluster) are also opened and are updated 
when the base cluster's contents change. 

UPGRADE — When the alternate index's base cluster is opened, the 
alternate index is also opened and will be updated to reflect any changes to 
the base cluster's contents, 

WRJTECHECK — Write operations are checked for correctness. 



The fields in this group are included by LISTCAT, as part of a volume entry, 
for each data space on the volume. If a volume contains no data spaces, it is a 
candidate volume. 

ATTRIBUTES — Describes the attributes of the data space. 

AUTOMATIC — The data space was created automatically by a 
secondary allocation operation. If a VSAM cluster must be given additional 
space on a volume and all existing data spaces are full, an existing data 
space will be extended, or a new one allocated on the volume, using catalog 
DADSM. A new data space so allocated is known as an implicit or 
automatic data space. 

EXPLICIT — The data space was created explicitly by a DEFINE 
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PROTECTION (PRT) 
RACF (PRT) 
HI-ALLOC-RBA (ALC) 
HI-USED-RBA (ALC) 
HI-ALLOC-RBA (VLS) 
HI-USED-RBA (VLS) 
READPW (PRT) 
RECOVERY (ATT) 
REC-DELETED (STA) 
REC-INSERTED (STA) 
REC-RETRIEVED (STA) 
REC-TOTAL (STA) 
REC-UPDATED (STA) 
RECORDS/CI (ATT) 
REPLICATE (ATT) 
RKP (ATT) 
REUSE (ATT) 
RECVABLE (ATT) 
SHROPTNS (ATT) 
SPACE-PRI (ALC) 
SPACE-SEC (ALC) 
SPACE-TYPE (ALC) 
SPEED (ATT) 
SPLITS-CA (STA) 
SPLITS-CI (STA) 
SPANNED (ATT) 
STATISTICS (STA) 
SUBALLOC (ATT) 
SWAP (ATT) 

SYSTEM-TIMESTAMP (STA) 
TEMP-EXP (ATT) 
TRACKS/CA (VLS) 
TRKOVFL (ATT) 
UNORDERED (ATT) 
UNIQUE (ATT) 
UNIQUEKEY (ATT) 
UPDATEPW (PRT) 
USAR (PRT) 
USVR (PRT) 
VOLFLAG (VLS) 
VOLSER (VLS) 
VOLUMES (VLS) 
WRITECHECK (ATT) 



Index Entry Keywords 

ALLOCATION (ALC) 

AIX (ASN) 

ASSOCIATIONS (ASN) 

ATTEMPTS (PRT) 

ATTRIBUTES (ATT) 

AVGLRECL (ATT) 

BIND (ATT) 

BUFSPACE (ATT) 

CI/CA (ATT) 

CISIZE (ATT) 

CLUSTER (ASN) 

CODE (PRT) 

CONTROLPW (PRT) 

CYLFAULT (ATT) 

DEVTYPE (VLS) 

DSTGWAIT (ATT) 

entryname (HIS) 

ERASE (ATT) 

EXCPEXIT (ATT) 

EXTENTS (STA) 

EXTENT-NUMBER (VLS) 

EXTENT-TYPE (VLS) 

EXTENTS (VLS) 

HIGH-CCHH (VLS) 
HIGH-RBA (VLS) 
LOW-CCHH (VLS) 
LOW-RBA (VLS) 
TRACKS (VLS) 

FREESPACE-%CI (STA) 

FREESPACE-%CA (STA) 

FREESPC-BYTES (STA) 

HIGH-KEY (VLS) 

HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 

IMBED (ATT) 



INDEX (STA) 

ENTRIES/SECT (STA) 
HI-LEVEL-RBA (STA) 
LEVELS (STA) 
SEQ-SET-RBA (STA) 
INH-UPDATE (ATT) 
KEYLEN (ATT) 
LOW-KEY (VLS) 
MASTERPW (PRT) 
MAXLRECL (ATT) 
NOERASE (ATT) 
NOIMBED (ATT) 
NOREPLICAT (ATT) 
NOREUSE (ATT) 
EXCPS (STA) 
EXTENTS (STA) 
NOTUSABLE (ATT) 
NOWRITECHK (ATT) 
ORDERED (ATT) 
PHYRECS/TRK (VLS) 
PHYREC-SIZE (VLS) 
PROTECTION (PRT) 
RACF (PRT) 
HI-ALLOC-RBA (ALC) 
HI-USED-RBA (ALC) 
HI-ALLOC-RBA (VLS) 
HI-USED-RBA (VLS) 
RECOVERY (ATT) 
READPW (PRT) 
REC-DELETED (STA) 
REC-INSERTED (STA) 
REC-RETRIEVED (STA) 
REC-TOTAL (STA) 
REC-UPDATED (STA) 
REPLICATE (ATT) 
RKP (ATT) 
REUSE (ATT) , 
SHROPTNS (ATT) 
SPACE-PRI (ALC) 
SPACE-SEC (ALC) 
SPACE-TYPE (ALC) 
SPEED (ATT) 
SPLITS-CA (STA) 
SPLITS-CI (STA) 
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STA: Statistics Group 



CODE — Gives the code used to tell the console operator what alternate 

index, catalog, cluster, path, data component, or index component requires 

him to enter a password. NULL is listed under CODE if a code is not ,^ 

used — the object requiring the password is identified with its full name. ^ 

CONTROLPW — The control-interval password (that is, the password for 
control-interval access). NULL indicates no control-interval password. 

MASTERPW — The master password. 

READPW — The read-only password. NULL indicates no read-only 
password. 

UPDATEPW — The update password. NULL indicates no update password. 

USAR — The contents (1 to 255 bytes, in character format) of the USAR 
(user-security-authorization record). This is the information specified in the 
string subparameter of the AUTH subparameter of the DEFINE command. 

USVR — The name of the USVR (user-security-verification routine) which is 
to be invoked to verify authorization of any access to the entry. 



The fields in this group give numbers and percentages that tell how much 
activity has taken place in the processing of a data or index component. The 
statistics in the catalog are updated when the data set is closed. Therefore, if a 
failure occurs during CLOSE, the statistics may not be valid. Since a VSAM 
catalog remains open from job to job, its statistics are not updated. 

FREESPACE-%CI — Percentage of space to be left free in a control interval 
for subsequent processing. 

FREESPACE-%CA — Percentage of control intervals to be left free in a 
control area for subsequent processing. 

FREESPC-BYTES — Actual number of bytes of free space in the total 
amount of space allocated to the data or index component. Free space in 
partially used control intervals is not included in this statistic, 

INDEX — This field appears only in an index entry. The fields under it 
describe activity in the index component. 

ENTRIES/SECT — The number of entries in each section of entries in an 
index record. 

HI-LEVEL-RBA — The RBA (relative byte address) of the highest-level 
index record. 

LEVELS — The number of levels of records in the index. The number is 
if no records have been loaded into the key-sequenced data set to which 
the index belongs. 

SEQ-SET-RBA — The RBA (relative byte address), in decimal, of the 
first sequence-set record. The sequence set might be separated from the 
index set by some quantity of RBA space. 

The remaining fields in the Statistics group (except for the System Timestamp 
field), are updated only when the data set is closed. 

EXCPS — EXCP (execute channel program — SVC 0) macro instructions 
issued by VSAM against the data or index component. 

EXTENTS — Extents in the data or index component. 
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DATASET-DIRECTORY (DSP) 

ATTRIBUTES (DSP) 

DSN (DSP) 

EXTENTS (DSP) 
DATASETS (DSP) 
DATASETS-ON-VOL (VOL) 
DATASPACE (DSP) 
DATASPCS-ON-VOL (VOL) 
DEVTYPE (VOL) 
EXTENT-DESCRIPTOR (DSP) 

BEG-CCHH (DSP) 

SPACE-MAP (DSP) 

TRACKS-TOTAL (DSP) 

TRACKS-USED (DSP) 
EXTENTS (DSP) 
FORMAT-1-DSCB (DSP) 

CCHHR (DSP) 

TIMESTAMP (DSP) 
MAX-PHYREC-SZ (VOL) 
MAX-EXT/ ALLOC (VOL) 
HISTORY (HIS) 

RCVY-CI (HIS) 

RCVY-DEVT (HIS) 

RCVY-VOL (HIS) 

RELEASE (HIS) 
SEC ALLOC (DSP) 
TRKS/CYL (VOL) 
TYPE (DSP) 

CYLINDER (DSP) 

TRACK (DSP) 
volume serial number (HIS) 
VOLUME-TIMESTAMP (VOL) 
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VOL: Volume Entry, Special Fields For 



The special fields for a volume entry describe the characteristics of the space 
that VSAM uses on the volume, 

volume serial number — The name of the cataloged volume entry. The volume 
serial number can be specified with the ENTRIES parameter of LISTCAT to 
identify the volume entry. 

BYTES/TRK — The number of bytes that VSAM can use on each track on 
the volume. 

CYLS/VOL — The number of cyUnders that VSAM can use on the volume, 
including alternate track cyUnders. 

DATASETS-ON-VOL — The number of VSAM clusters that reside, in 
whole or in part, on the volume. Should the number of data spaces be zero, 
then this is a candidate volume only and this group is omitted. 

DATASPCS-ON-VOL — The number of VSAM data spaces on the volume. 
Should the number of data spaces be zero, then this is a candidate volume 
only, and the data space group is omitted. 

DEVTYPE — The type of device to which the volume belongs. (See the 
Device Type Translate Table at the end of this section for a translation of the 
hexadecimal device type to its equivalent EBCDIC value.) 

MAX-PHYREC-SZ — The size of the largest physical record that VSAM 
can write on the volume. 

MAX-EXT/ ALLOC — The maximum number of extents that can be 
allocated per each allocation request for a single data set on the volume. 

TRKS/CYL — The number of tracks in each cylinder on the volume. 

VOLUME-TIMESTAMP — The time (System/370 thne-of-day clock value) 
VSAM last changed the contents of the volume. The format-4 DSCB contains 
the timestamp at offset 76 (X'4C'). 



Device Type Translate Table 



LISTCAT Code 


Device Type 


300«1 


8001 


9 TRK TAPE 


3040 


200A 


3340 (35M/70M) 


3050 


2006 


2305-1 


3050 


2007 


2305-2 


3050 


2009 


3330 


3050 


200B 


3350 


3050 


200D 


3330-1 


3058 


2009 


3330V 


3080 


8001 


7 TRK TAPE 


30C0 


2008 


2314/2319 
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- Its associated nonVSAM data set entry. 

- A user catalog entry. (All alias entries for a nonVSAM data set entry 
are chained together, as are alias entries for a user catalog entry.) 

• An alternate-index entry points to: 

- Its associated data and index entries. 

- Its base cluster's cluster entry. 

- Each associated path entry. 

• An alternate-index's data entry points to: 

- Its associated alternate-index entry. 

• An alternate-index's index entry points to: 

- Its associated alternate-index entry. 

• A cluster entry points to: 

- Its associated data entry. 

- Each associated path entry. 

- For a key-sequenced cluster, its associated index entry. 

- For a cluster with alternate indexes, each associated alternate index 
entry. 

• A cluster's data entry points to: 

- Its associated cluster entry. 

. A duster's index entry points to: 

- Its associated cluster entry. 

• A generation data group base entry points to: 

- Its associated nonVSAM data set entries. 

• A nonVSAM data set entry points to: 

- Its associated aUas entry. 

- Its associated generation data group (for a GOOOOVOO nonVSAM). 

• A page space entry points to: 

- Its associated data entry. (The page space is cataloged as an 
entry-sequenced cluster with a cluster entry and an associated data 
entry.) 

• A path entry (that establishes the connection between a base cluster and 
an alternate index) points to: 

- Its associated alternate index entry, and the alternate index's associated 
data and index entries. 

- The data entry of its associated base cluster. 

- For a key-sequenced base cluster, the index entry of its associated base 
cluster. 
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When you specify LISTCAT without any parameters, the entryname and type 
of each entry is listed (see Figure 17). The same listing would result. if the 
NAMES parameter were specified. 

You can use this type of listing to list the name of each cataloged object and 
to determine the number of entries in the catalog. The total number of entries 
is an approximate size, in records, of your catalog. 



/* LIST ENTRYNAMES OF THE CATALOG */ 
LISTCAT - 

CATALOG (MJKCAT) 





LISTING FROM CATALOG - 


- MJKCAT 








DATA 


■— MJK.ALT.INDEX1.DATA 




INDEX 


- - MJK . ALT . INDEX 1 . INDEX 




PATH 


— MJK. A1X1. PATH 




CLUSTER 


— MJK.CLUSTER1 




DATA 


— MJK. CLUSTER. DATA 




INDEX 


— MJK. CLUSTER 1 .INDEX 




GDG BASE 


■— MJK.GDG1 




NONVSAM — 


— MJK.GDG1 .G0001V00 










NONVSAM 


— MJK.N0NVSAM1 




CLUSTER 


— MJKCAT 




DATA 


— VSAM. CATALOG. BASE. DATA. RECORD 




INDEX 

VOLUME 


•-- VSAM. CATALOG. BASE. INDEX. RECORD 
-- 333001 





LISTING FROM CATALOG -- MJKCAT 

THE NUMBER OF ENTRIES PROCESSED WAS: 

AIX 1 

ALIAS 1 

CLUSTER 2 

DATA 3 

GDG — 1 

INDEX 3 

NONVSAM 2 

PAGESPACE 

PATH 1 

SPACE --1 

USERCATALOG 

TOTAL 15 

THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 

IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 

Figure 17. An Example of LISTCAT Output When No Parameters are Specified 
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INH-UPDATE — The data component cannot be updated. Either the data 
component was exported with INHIBITSOURCE specified, or its entry was 
I modified by way of ALTER, with INHIBIT specified. 

i INDEXED — The data component has an index — ^it is key-sequenced. 

KEYLEN — The length of the key field in a data record. 

MAXLRECL — The maximum length of data or index records. AVGLRECL 
equals MAXLRECL when the records are fixed-length. 

MAXRECS — Identifies the highest possible valid relative-record number, 
for a relative-record data set. This value is calculated as follows: 

232/CISIZE X number of records slots per control interval. 

NOERASE — Records are not to be erased (set to binary Os) when deleted. 

NOIMBED — The sequence-set index record is not stored along with its 
associated data control area. 

NONINDEXED — The data component has no index — it is entry-sequenced. 

NONSPANNED — Data records cannot span control intervals. 

NONUNIQKEY — Indicates, for an alternate index, that more than one data 
record in the base cluster can contain the same alternate-key value. 

NOREPLICAT — Index records are not repUcated. 

NOREUSE — The data set cannot be reused. 

NOSWAP — The page space is a conventional page space and cannot be 
used as a high speed swap data set. 

\ NOTRKOVFL — The physical blocks of a page space data set cannot span a 

track boundary. 

NOUPDATE — When the path is opened for processing, its associated base 
cluster is opened but the base cluster's upgrade set is not opened. 

NOUPGRADE — The alternate index is not upgraded unless it is opened and 
being used to access the base cluster's data records. 

NOTUSABLE — The entry is not usable because (1) the catalog could not 
be correctly recovered by RESETCAT or (2) a DELETE SPACE FORCE 
was issued for a volume (s) in the entry's volume list. 

NOWRl 1 ECHK — Write operations ire not checked for correctness. 

NUMBERED — The cluster is a relative-record data set. 

ORDERED — Volumes are used for space allocation in the order they were 
specified when the cluster was defined. 

RECOVERY — A temporary CLOSE is issued as each control area of the 
data set is loaded, so the whole data set won't have to be reloaded if a serious 
error occurs during loading. . 

RECORDS/CI — Specifies the number of records, or slots, in each control 
interval of a relative-record data set. 

RECVABLE — This attribute is set in the data entry of a recoverable catalog, 
and each of the catalog's volumes contains a catalog recovery area. 

REPLICATE — Index records are replicated (that is, each is duplicated 
\, around a track of the index's direct-access device). 
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CLUSTER MJK 

HISTORY 

OWNER- IDENT- 
RELEASE 



■(NULL) 
2 



CREATION— 
EXPIRATION- 



DATA VS AM. CATALOG. BASE. DATA. RECORD 

HISTORY 

OWNER-IDENT (NULL) CREATION— - 

RELEASE 2 EXPIRATION- 
VOLUMES 

VOLSER 333001 DEVTYPE 



-77.040 
-99.999 



-00.000 
-00.000 



-X' 30502009' 



INDEX — 

HISTORY 

OWNER-IDENT 
RELEASE 

VOLUMES 

VOLSER 



VSAM . CATALOG . BASE . INDEX . RECORD 



(NULL) 

2 



CREATION— - 
EXPIRATION- 



-00.000 
-00.000 



-X' 30502009' 



VOLUME 

HISTORY 

RELEASE- 
VOLUMES 

VOLSER- - 



-333001 DEVTYPE X' 30502009' 

LISTING FROM CATALOG -- MJKCAT 



RCVY-DEVT X ' 30502009 ' 



THE NUMBER OF ENTRIES PROCESSED WAS: 

AIX 1 

ALIAS 

CLUSTER 2 

DATA 3 

GDG 1 

INDEX 3 

NONVSAM 2 

PAGESPACE 

PATH 1 

SPACE 1 

USERCATALOG 

TOTAL 14 

THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 

IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 

Figure 18 (Part 2 of 2). An Example of LISTCAT VOLUME Output 
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\ 



MASTERCATALOG or USERCATALOG command, or a DEFINE 
ALTERNATEINDEX or DEFINE CLUSTER command with the 
UNIQUE attribute specified or by a DEFINE SPACE command. 

MASTERCAT — The data space contains the master catalog. 

SUBALLOC — The data space might contain several VSAM clusters. 

USERCAT — The data space contains a user catalog. 

UNIQUE — The data space contains a single (unique) VSAM cluster or 
catalog. 

DATASET DIRECTORY — Lists the VSAM data sets that can be stored 
(see CANDIDATE below) or actually are stored (in whole or in part) in the 
data space. 

ATTRIBUTES — Describes the relation between the named data set and 
the data space. 

CANDIDATE — The volume is a candidate for storing the data set 

(NULL) — The data set is stored (in whole or in part) in the data space 

DSN — The data-set name of the object that can be stored or is stored on 
the volume. 

EXTENTS — The number of data set extents for the data set within the 
data space. 

DATASETS — The number of VSAM data sets stored (in whole or in part) 
in the data space. (The number includes data sets for which the volume is a 
candidate.) 

EXTENT-DESCRIPTOR — Describes the data space extent. 



y BEG-CCHH — The device address (that is, CC = cyUnder and HH = 

track) of the extent. 

SPACE-MAP — A hexadecimal number that tells what tracks are used 
and what tracks are free in the extent. The number consists of one or more 
RLCs (run length codes). The first RLC gives the number of contiguous 
used tracks, starting at the beginning of the extent; if all of the tracks in 
the extent are used, there is only one RLC. The second RLC gives the 
number of contiguous free tracks, beyond the used tracks. A third RLC 
gives used tracks again, a fourth gives free tracks, and so on. 

A 1-byte RLC gives the number of tracks less than 250; a 3-byte RLC 
gives the number of tracks equal to or greater than 250. That is, if the first 
byte of an RLC is X'F9' (249) or less, it is the only byte of the RLC and 
gives the number of tracks. If the first byte of an RLC is X'FA' (250) or 
more, the byte is followed by two more bytes that give the number of 
tracks (the first byte means nothing more than to look at the next two 
bytes). 

TRACKS-TOTAL — Allocated to the data space altogether. 

TRACKS-USED — Used to store data. 

EXTENTS — The number of data space extents in the data space. 
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LISTCATALL Output Listing 



When you specify the LISTCAT command and include the ALL parameter, 
all the information for each catalog entry is listed (see Figure 20). This 
example illustrates the LISTCAT output for each type of catalog entry. You 
can use this type of listing to obtain all cataloged information (except 
password and security information) about each entry that is listed. When you 
want to list an entry's passwords, you must provide the catalog's master 
password (which results in listing the passwords of each password-protected 
entry) or each entry's master password. 

Note: When ENTRIES is specified, you specify only those entrynames that 
identify catalog entries which are not volume entries. If a volume serial 
number is specified with the ENTRIES parameter, than entrynames of other 
entry types cannot also be specified. However, if the ENTRIES parameter is 
not specified and if entry types are not specified (that is, CLUSTER, SPACE, 
DATA, etc.), all entries in the catalog, including volume entries, are listed. 



LIST ALL CATALOGED INFORMATION FOR EACH ENTRY */ 
LISTCAT - 
ALL - 
CATALOG (MJKCAT) 

LISTING FROM CATALOG — MJKCfl 



< MJK.ALT.INDEX1 

HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 

PROTECTION-PSWD (NULL) 

ASSOCIATIONS 

DATA MJK. ALT. INDEX 1 .DATA 

INDEX MJK. ALT. INDEX1 .INDEX 

CLUSTER--MJK.CLUSTER1 
PATH MJK.AIX1 .PATH 

ATTRIBUTES 
UPGRADE 

DATA MJK.ALT.INDEX1 .DATA 

HISTORY 

Ol-TOER-IDENT (NULL) 

RELEASE 2 

PROTECTION-PSWD (NULL) 

ASSOCIATIONS 

AIX MJK. ALT. INDEX 1 

ATTRIBUTES 

KEYLEN 5 

RKP 5 

AXRKP 45 

SHROPTNS (1,3) RECOVERY 
UNORDERED NOREUSE 

STATISTICS 

REC-TOTAL 4 

REC-DELETED 

REC-INSERTED 

REC-UPDATED 

REC-RETRIEVED 

ALLOCATION 

SPACE-TYPE TRACK 

SPACE-PRI 6 

SPACE-SEC 6 

VOLUME 

VOLSER 333001 

DEVTYPE X' 30502009' 

VOLFLAG PRIME 

EXTENTS : 

LOW-CCHH X ' 00040008 ' 

HIGH-CCHH X'0004000D' 



CREATION 

EXPIRATION- 
RACP 



-77.040 
-00.000 
— (NO) 



RCVY-VOL 333001 

RCVY-DEVT X ' 30502009 ' 



CREATION- — 77 . 040 

EXPIRATION 00 . 000 

RACF (NO) 



AVGLRECL- 
MAXLRECL- 



--4086 
-32600 



SUBALLOC 

SPANNED 



NOERASE 
NONUNIQKEY 



SPLITS-CI 

SPLITS-CA 

FREESPACE-XCI 

FREESPACE-XCA 

FREESPC-BYTES 69632 



HI-ALLOC-RBA- 
HI-USED-RBA— 



-73728 
-73728 



PHYREC-SIZE- 
PHYRECS/TRK- 
TRACKS/CA 



-4096 
3 

6 



LOW-RBA 

HIGH-RBA- 73727 



RCVY-VOL 333001 

RCVY-DEVT X' 30502009' 

BUFSPACE 8704 

EXCPEXIT (NULL) 

INDEXED NOWRITECHK 

EXCPS 7 

EXTENTS 1 

SYSTEM-TIMESTAMP : 

X • 8A5 1 B6C0C87CF000 ' 



HI-ALLOC-RBA 73728 

HI-USED-RBA 73728 

TRACKS 6 



CISIZE- 
CI/CA-- 



-4096 
— -18 



NOREPHCAT 



EXTENT-NUMBER- 
EXTENT-TYPE 



Figure 20 (Part 1 of 5). An Example of LISTCAT ALL Output 
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mS: History Group 



The fields in this group identify the object's owner, identify its catalog 
recovery volume and release level, and give its creation and expiration dates. 

entryname — The name of the cataloged object. The entryname can be 
specified with the ENTRIES parameter of LISTCAT to identify a catalog 
entry. 

HISTORY — This field includes the following fields: 

CREATION — The Julian date (YY.DDD) on which the entry was 
created. This field will always contain 00.000 for a nonVSAM data set 
entry in an OS CVOL. 

EXPIRATION — The Julian date (YY.DDD) after which the entry can be 
deleted without specifying the PURGE parameter in the DELETE 
command. Julian date 99.999 indicates that PURGE is always required to 
delete the object. This field will always contain 00.000 for a nonVSAM 
data set entry in an OS CVOL. 

OWNER-IDENT — The identity of the owner of the object described by 
the entry. 

RCVY-CI — If the entry is in a recoverable catalog, this field contains the 
control interval number in the catalog recovery area where a duplicate of 
the entry can be found. 

RCVY-DEVT — If the entry is in a recoverable catalog, this field identifies 
the recovery- volume's device type. (See the Device Type Translate Table 
at the end of this section for a translation of the hexadecimal device type to 
its equivalent EBCDIC value.) 

RCVY-VOL — If the entry is in a recoverable catalog, this field contains 
the recovery-volume's serial number. 

RELEASE — The release of VSAM under which the entry was created 
(not the same as the release number of OS/VS2): 

1 = OS/VS2 Releases 3 and releases previous to Release 3 

2 = OS/VS2 Release 3.6 and any later releases 



PRT: Protection Group 



The fields in this group describe how the alternate index, cluster, data 
component, index component, or path defined by the entry is password 
protected or RACE protected. NULL or SUPPRESSED might be listed under 
password protection and YES or NO might be listed under RACE protection. 

NULL indicates that the object defined by the entry has no passwords. 

SUPP indicates that the master password of neither the catalog nor the entry 
was specified, so authority to list protection information is not granted. 

RACE — Indicates whether or not the entry is protected by the RESOURCE 
Access Control Facility. 

YES — Entry is RACE protected. 

NO — ^Entry is not RACE protected. 

ATTEMPTS — Gives the number of times the console operator is allowed to 
attempt to enter a correct password. 
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VOLUME -. 33300 

HISTORY 

RELEASE 

CHARACTERISTICS 

BYTES/TRK 

TRKS/CYL 

CYLS/VOL 

DATASPACE 

DATASETS 

EXTENTS 

SEC-ALLOC 

TYPE 



-13165 

19 

-—411 



5 

1 

40 

-TRACK 



DEVTYPE X' 30502009' 

VOLUME-TIMESTAMP : 

X ' 8A5 1 B6A76850E000 ' 

FORMAT- 1-DSCB: 

CCHHR X' 0000000 103' 

TIMESTAMP 

X'"8A51B61D97B04000' 



BEG-CCHH- 



-X'00000002' 



RCVY-DEVT X ' 30502009 ' 



MAX-PHYREC-S2- 
MAX-EXT/ALLOC- 



-13030 

5 



DATASETS-ON-VOL- 
DATASPCS-ON-VOL- 



EXTENT- DESCR I PTOR : 

TRACKS-TOTAL 160 

TRACKS-USED 89 

DATASET-DIRECTORY : 

DSN MJKCAT 

DSN MJK . CLUSTER . DATA 

DSN MJK.CLUSTER1 .INDEX 

DSN MJK.ALT.INDEX1.DATA 

DSN MJK. ALT. INDEX 1. INDEX 

LISTING FROM CATALOG — MJKCAT 

THE NUMBER OF ENTRIES PROCESSED WAS: 

AIX 1 

ALIAS 1 

CLUSTER 2 

DATA 3 

GDG 1 

INDEX 3 

NONVSAM ,2 

PAGESPACE 

PATH • — 1 

SPACE 1 

USERCATALOG ■ 

TOTAL 15 

THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 

IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 

Figure 20 (Part 5 of 5). An Example of LISTCAT ALL Output 



ATTRIBUTES: 
SUBALLOC 
EXPLICIT 
USERCAT 

SPACE -MAP 5947 

ATTRIBUTES (NULL) 

ATTRIBUTES (NULL) 

ATTRIBUTES (NULL) 

■ATTRIBUTES (NULL) 

ATTRIBUTES (NULL) 



EXTENTS 3 

EXTENTS 1 

EXTENTS 1 

EXTENTS 1 

EXTENTS 1 
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REC-DELETED — The number of records that have been deleted from the 
data or index component. Statistics for records deleted are not maintained 
I when the data set is processed in control interval mode. 

REC-INSERTED — For a key-sequenced data set, the number of records 
that have been inserted into the data component before the last record; 
records originally loaded and records added to the end are not included in this 
statistic. For relative-record data sets, it is the number of records inserted into 
available slots; the number of records originally loaded are included in this 
statistic. Statistics for records inserted are not maintained when the data set is 
processed in control interval mode. 

REC-RETRIEVED — The number of records that have been retrieved from 
the data or index component, whether for update or not for update. Statistics 
for records retrieved are not maintained when the data set is processed in 
control interval mode. 

REC-TOTAL — The total number of records actually in the data or index 
component. This statistic is not maintained when the data set is processed in 
control interval mode. 

REC-UPDATED — The number of records that have been retrieved for 
update and rewritten. This value does not reflect those records that were 
deleted, but a record that is updated and then deleted is counted in the update 
statistics. Statistics for records updated are not maintained when the data set 
is processed in control interval mode. 

SPLITS-CA — Control-area splits. Half the data records in a control area 
were written into a new control area and then were deleted from the old 
control area. 

SPLITS-CI — Control-interval splits. Half the data records in a control 
'' interval were written into a new control interval and then were deleted from 

the old control interval. 

SYSTEM-TIMESTAMP — The time (System/370 time-of-day clock value) 
the data or index component was last closed (after being opened for' 
operations that might have changed its contents). 
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LISTCA THISTOR Y Output Listing 



When you specify the LISTCAT command and include the HISTORY 
parameter, only the name, ownerid, creation date, and expiration date are 
listed for each entry that is selected (see Figure 22). Only these types of 
entries have HISTORY information: ALTERNATEINDEX, CLUSTER, 
DATA, INDEX, NONVSAM, and PATH. 



/* LIST HISTORY INFORMATION FOR EACH ENTRY */ 

LISTCAT - 
HISTORY - 
CATALOG (MJKCAT) 

LISTING FROM CATALOG 

AIX ~ MJK. ALT. INDEX 1 



HISTORY 

OWNER-IDENT- 
RELEASE 



CREATION- — 
EXPIRATION- 



-77.040 
-00.000 



DATA MJK. ALT. INDEX 1. DATA 

HISTORY 

OWNER-IDENT -"-(NULL) CREATION 77.040 

RELEASE 2 EXPIRATION 00.000 



MJK . ALT . INDEX 1 . INDEX 



INDEX -- 
HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 

PATH MJK. AIX1 .PATH 

HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 



CREATION 

EXPIRATION- 



-77.040 
-00.000 • 



CREATION 77.040 

EXPIRATION 00 . 000 



CLUSTER 

HISTORY 

OWNER-IDENT 
RELEASE 



MJK. CLUSTER 1 



-OWNCLUST 

2 



CREATION — 
EXPIRATION- 



DATA MJK. CLUSTER. DATA 

HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 



CREATION 

EXPIRATION- 



INDEX — 
HISTORY 

OWNER-IDENT 
RELEASE 



MJK. CLUSTER 1 .INDEX 



■(NULL) 

2 



CREATION 

EXPIRATION- 



■77, 


,040 


■77, 


.140 


■77, 


,040 


■00, 


.000 


■77, 


.040 


■00 


.000 



GDG BASE -- 
HISTORY 

OWNER-IDENT 
RELEASE 



MJK.GDG1 



NONVSAM 

HISTORY 

OWNER-IDENT 
RELEASE 



— OWNGDG 

2 

— MJK.GDG1 .G0001V00 



CREATION 75.223 

EXPIRATION 99 . 365 



■(NULL) 



CREATION 

EXPIRATION- 



-77.040 
-00.000 



ALIAS MJK. GDG1. ALIAS 

HISTORY 

RELEASE 2 



NONVSAM MJK.N0NVSAM1 

HISTORY 


CREATION 

EXPIRATION-- — 


77. 

00. 


,040 
,000 










CLUSTER MJKCAT 

HISTORY 




CREATION 

EXPIRATION 


77, 

99, 


.040 
,999 


RELEASE 


2 


DATA VSAM. CATALOG. BASE. 

HISTORY 


. DATA . RECORD 

CREATION 

EXPIRATION 


00 

00 


.000 
.000 


RELEASE 


2 



VSAM . CATALOG . BASE . INDEX . RECORD 



INDEX -- 

HISTORY 

OWNER-IDENT (NULL) 

RELEASE 2 



CREATION 00 . 000 

EXPIRATION 00.000 



VOLUME 

HISTORY 
RELEASE 



333001 

2 RCVY-VOL 3 33001 

Figure 22 (Part 1 of 2).. An Example of LISTCAT HISTORY 



RCVY-VOL 333001 

RCVY-DEVT X' 30502009' 

RCVY-VOL 333001 

RCVY-DEVT X ' 30502009 ' 

RCVY-VOL 333001 

RCVY-DEVT X' 30502009' 

RCVY-VOL 333001 

RCVY-DEVT X ' 30502009 • 

RCVY-VOL 333001 

RCVY-DEVT X' 30502009' 

RCVY-VOL 333001 

RCVY-DEVT X* 30502009' 

RCVY-VOL 333001 

RCVY-DEVT X' 30602009' 

RCVY-VOL 333001 

RCVY-DEVT X ' 30502009 ' 

RCVY-VOL 333001 

RCVY-DEVT X' 30502009" 

RCVY-DEVT X' 30502009' 

RCVY-VOL 333001 

RCVY-DEVT X' 30502009' 



RCVY-DEVT X' 30502009' 

Output 



RCVY-CI X ' 000014 ' 



RCVY-Cl X ' OOOOOF' 



RCVY-CI X' 00001 5' 



RCVY-CI X ' 000016 ' 



RCVY-CI X' 00001 8' 



RCVY-CI X ' 000009 ' 
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TRACKS — The number of tracks in the extent, from low to high device 
addresses. 

fflGH-KEYi — For a key-sequenced data set with the KEYRANGE 
attribute, the highest hexadecimal value allowed on the volume in the key 
field of a record in the key range. A maximum of 64 bytes can appear in 
HIGH-KEY. 

HI-KEY-RBAi — For a key-sequenced data set, the RBA (relative byte 
address), in decimal, of the control interval on the volume that contains the 
highest keyed record in the data set or key range. 

LOW-KEYi — For a key-sequenced data set with the KEYRANGE 
attribute, the lowest hexadecimal value allowed on the volume in the key field 
of a record in the key range. A maximum of 64 bjrtes can appear in 
LOW-KEY. 

PHYRECS/TRK — The number of physical records (of the size indicated 
under FHYRECS-SIZE) that VSAM can write on a track on the volume. 

PHYREC-SIZE — The number of bytes that VSAM uses for a physical 
record in the data or index component. 

HI-ALLOC-RBA — The highest RBA (plus 1) available within allocated 
space to store data component, its key range, the index component, or the 
sequence set records of a key range. 

HI-USED-RBA — The highest RBA (plus 1) within allocated space that 
actually contains data component, its key range, the index component, or the 
sequence set records of a key range. 

TRACKS/CA — The number of tracks in a control area in the data 
component. (This value is computed when the entry is defined, and reflects 
the optimum size of the control area for the given device type and the nature 
of the entry — ^whether indexed, nonindexed, or numbered.) For a 
key-sequenced data set with the imbedded attribute, this value includes the 
sequence set track. 

VOLFLAG — Indicates whether the volume is a candidate volume or the first 
or a subsequent volume on which data in a given key range is stored. 

CANDIDATE — The volume is a candidate for storing the data or index 
component. 

OVERFLOW — The volume is an overflow volume on which data records 
in a key range are stored. The KEYRANGE begins on another (PRIME) 
volume. 

PRIME — The volume is the first volume on which data records in a key 
range aie stored. 

VOLSER — The serial number of the volume. 



* Multiple keyranges might reside on a single volume — ^the 
, volumes group is repeated for each such key range field. 
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Examples of USTCAT in a TSO Environment 



The following examples illustrate the output produced at a TSO terminal for a 
LISTCAT NAMES (default) and LISTCAT VOLUME. A TSO logon ID of 
IBMUSER is assumed. 

For LISTCAT NAMES, the catalog name is printed followed by the names of 
all entries that have a high-level qualifier equal to the USER logon ID. 

For LISTCAT VOLUME, all entrynames that have a high-level quahfier 
equal to the USER logon ID are printed followed by the volume serial 
numbers for those entries that contain volume information. 

Note: Because volume serial numbers for a cluster or an alternate index are 
contained in the data and index components, the data and index must have 
been named on the initial DEFINE in order to list the. volume serial numbers. 

LOGON IBMUSER 



READY 
LISTCAT 

IN CATALOG: AMASTCAT 
IBMUSER. AIX 
IBMUSER. AIXDATA 
IBMUSER. AIXIDX 
IBMUSER. GDG 
IBMUSER . GDG . GOOO 1 VOO 
IBMUSER . GDG . G0002V00 
IBMUSER . GDG . GOOO 3 VOO 
IBMUSER. KSDS 
IBMUSER. KSDSDATA 
IBMUSER. KSDSIDX 
IBMUSER. NVSAM1 
IBMUSER. NVSAM2 
IBMUSER. NVSAM3 
IBMUSER . NVSAM4 
IBMUSER. NVSAM5 
READY 

LISTCAT VOLUME 

IBMUSER. AIX 
IBMUSER . AIXDATA 
— VOLUMES — 

333001. 

IBMUSER. AIXIDX 

—VOLUMES— 

333001 
IBMUSER . GDG 
IBMUSER. GDG . GOOO 1 VOO 
—VOLUMES— 

333001 

333002 

333003 
IBMUSER . GDG . G0002V00 
—VOLUMES — 

333004 

333005 

333006 

333007 

333008 
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IBMUSER . GDG . G0003V00 
—VOLUMES — 
333009 
333010 
IBMUSER. KSDS 
IBMUSER . KSDSDATA 
—VOLUMES— 
333001 
IBMUSER. KSDSIDX 
—VOLUMES— 
333001 
IBMUSER. NVSAM1 
—VOLUMES— 
231401 
231402 
IBMUSER. NVSAM2 
—VOLUMES — 
231403 
231404 
231405 
IBMUSER . NVSAM3 
—VOLUMES — 
231406 
IBMUSER. NVSAM4 
—VOLUMES— 
231407 
IBMUSER.NVSAM5 
—VOLUMES— 
231408 
231409 
231410 
231411 
231412 
READY 
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APPENDIX C: JCL DD PARAMETERS TO TAKE 
CARE WITH 



Because OS/VS does not disallow any DD statement parameters and 
subparameters for VSAM, you should be aware of the specifications that 
either do nothing in a VSAM environment or might cause problems for you. 
Figure 24 shows the DD statement parameters and subparameters to be 
avoided with VSAM. 



Parameter 
AFF 

CHKPT 

DATA 

DCB 



DISP 



DSNAME 



Subparameter 

ddname 

EOV 



All 



CATLG 

DELETE 

MOD 

KEEP 

NEW 



UNCATLG 

dsname(areaname) 

dsname(generation) 

dsname(meniber) 

All temporary 
dsnames 

All backward 
DD references 
of the form 
*. ddname 



Comment 

You must use this parameter carefully. If the cluster components, the data and its index, 
reside on unlike devices, the results of an AFF specification are unpredictable. 

Because checkpoints at end of volume are executed only for BSAM and QSAM data sets, 
this parameter does not apply to VSAM data sets and need not be coded. 

Because there is no way to get VSAM data into the input stream, this parameter is not 
applicable to VSAM. 

The access-method control block (ACB)j not the DCB, describes VSAM data sets; 
therefore, the DCB parameter is not applicable to VSAM. An access-method control 
block is generated by an ACB or GENCB macro, and can be modified by a MODCB 
macro. 

VSAM data sets are cataloged and uncataloged as a result of an Access Method Services 
command; if CATLG is coded, a message is issued, but the data set is not cataloged. 

VSAM data sets are deleted as a result of an Access Method Services command; if 
DELETE is coded, a message is issued, but the data set is not deleted. 

For VSAM data sets, MOD is treated as if OLD were specified, except for processing 
with an ISAM program, in which case MOD indicates resume load. 

Because KEEP is implied for VSAM data sets, it need not be coded. 

VSAM data spaces are initially allocated as a result of the Access Method Services 
DEFINE command. If NEW is specified, OS/VS also allocates space, and it is never used 
by VSAM. Moreover, an Access Method Services request for space may fail if the 
DISP=NEW acquisition of space causes too little space to remain available. 

VSAM data sets are cataloged and uncataloged as a result of Access Method Services 
commands; if UNCATLG is coded, a message is issued, but the data set is not 
uncataloged. 

The name is used; areaname is ignored. 

A generation data group entry must exist in the VSAM catalog for this to apply. 

The name is used; member is ignored. 

Because VSAM data sets are built by Access Method Services, which uses the 

data-set name supplied in the DEFINE command; temporary names cannot be used with 

VSAM. 

If the object referred to is a cluster and the data set and index reside on unlike 
devices, the results of a backward DD reference are unpredictable. 



Figure 24 (Part 1 of 2). JCL DD Parameters 
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Parameter 
LABEL 



LABEL 



SEP 
SPACE 

SPLIT 

SUBALLOC 



Subparameter 

BLP, NL, NSL 

IN 

OUT 

NOPWREAD 

PASSWORD 

SL, SUL 

ddname 



SYSOUT 




UCS 


All 


UNIT 


AFF 




SEP 


VOLUME 


REF 




volseqt 




volcount 



Comment 

Because these subparameters have no meaning for direct-access devices, they do not 
apply for VSAM data sets, which all reside on direct-access storage. 

Because IN is used to override DCB subparameters and the DCB parameter does not 
apply to VSAM data sets, IN does not apply. 

Because OUT is used to override DCB subparameters and the DCB parameter does not 
apply to VSAM data sets, OUT does not apply. 

The password-protection bit is set for all VSAM data sets, regardless of the 
PASSWORD/NOPWREAD specification in the LABEL parameter. 

The password-protection bit is set for all VSAM data sets, regardless of the 
PASSWORD/NOPWREAD specification in the LABEL parameter. 

Although these parameters apply to direct-access storage devices, SL is always used for 
VSAM, whether you specify SL, SUL, or neither. 

You must use this parameter carefully. If the cluster components, the data and its index, 
reside on unlike devices, the results of a SEP specification are unpredictable. 

VSAM data spaces are initially allocated as a result of the Access Method Services 
DEFINE command. If SPACE is specified, therefore, an extent is allocated that is never 
used by VSAM. Moreover, an Access Method Services request for space may fail as a 
result of the SPACE acquisition of space. 

VSAM data spaces are initially allocated as a result of the Access Method Services 
DEFINE command. If SPLIT is specified, OS/VS also allocates space, and it is never 
used by VSAM. Moreover, an Access Method Services request for space may fail if the 
SPLIT acquisition of space causes too little space to remain available. 

VSAM data spaces are initially allocated as a result of the Access Method Services 
DEFINE command. If SUBALLOC is specified, OS/VS also allocates space, and it is 
never used by VSAM. Moreover, an Access Method Services request for space may fail if 
the SUBALLOC acquisition of space causes too little space to remain available. If the 
data set for which SUBALLOC is specified is a VSAM data set, the request is denied. 

If SYSOUT is coded with a mutually exclusive parameter (for example, DISP), the job 
step is terminated with an error message. 

Because this parameter applies only to unit-record devices, it does not apply to VSAM. 

You must use this subparameter carefully. If the cluster components, the data and its 
index, reside on unlike devices, the results of UNIT=AFF are unpredictable. 

You must use this subparameter carefully. If the cluster components, the data and its 
index, reside on unlike devices, the results of UNIT=SEP are unpredictable. 

You must use this subparameter carefully. If the referenced volumes are not a subset of 
those contained in the catalog record for the data set, the results are unpredictable. 

Results are unpredictable. 

This subparameter is used to request some number of nonspecific volumes. Because all 
VSAM volumes must be specifically defined before processing, volcount is not applicable 
to VSAM data sets. 



I 



Figure 24 (Part 2 of 2). JCL DD Parameters 
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APPENDIX D: INTERPRETING LISTCRA OUTPUT 
LISTINGS 



When you code the LISTCRA command, you can specify options that allow 
you to tailor the contents of the LISTCRA output. This appendix illustrates 
the various types of the LISTCRA output, the order in which entries are 
listed, and the meanings of the listed fields. 

There are five types of LISTCRA listings. Four of the types are illustrated in 
this appendix. The fifth type, SEQUENTIALDUMP, is exactly the same as 
the DUMP NOCOMPARE type except that the entries are not sorted into 
groups. 

Each listed entry is identified by type (that is, cluster, nonVSAM, etc.) and 
by name. Entries are usually listed in alphabetical order within groups of 
entries, according to entryname (except for SEQUENTIALDUMP). 
However, if insufficient virtual storage is available for the sorting operation, 
the records are listed as they appear in the catalog recovery area. 

On the listing, entries are sorted into three groups (except for a 
SEQUENTIALDUMP listing): 

• VSAM entries (which are also sorted according to entryname). Cluster 
entries, alternate index entries, and their associated data, index, and path 
entries are within this group. 

• Other entries that are sorted according to entryname. User catalog 
connector entries and nonVSAM entries are in this group. 

• Unsorted entries: other entries that are not sorted according to entryname. 
Entries that are listed within this group depend on the type of LISTCRA 
listing requested. 

The following list contains the abbreviation, type, and description for each 
kind of entry that can be listed as a result of the LISTCRA command: 

Description 

Alternate index entry 

Alias entry 

Cluster entry 

Data component entry 

Freespace entry 

Generation data group entry 

Index component entry 

NonVSAM data set entry 

Extension record for an entry other than a volume entry 

Path entry 

User catalog connector entry (in the master catalog only) 

Upgrade set entry 

Extension record for a volume entry 

Volume entry 



Abbreviation - 


Type 


AIX 


G 


ALIA 


X 


CLUS 


C 


DATA 


D 


FRSP 


F 


GDGB 


B 


INDX 


I 


NONV 


A 


OEXT 


E 


PATH 


P 


UCAT 


U 


UPGD 


Y 


VEXT 


W 


VOL 


V 
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Examples of LISTCRA Listings 

The five types of LISTCRA listings are: 



NAME NOCOMPARE — This is the default option. Each entryname, its 
volumes, and the name and volumes of each related entry is Usted. Within 
the "unsorted entries" group, all catalog records not yet printed are 
printed. See Figure 25. 

DUMP NOCOMPARE— When DUMP is specified (NOCOMPARE is a 
default), each record is Usted in the dump format. In addition, the name 
and volumes of each indirectly related entry are also listed. Within the 
"unsorted entries" group, the CRA's self -describing records (control 
intervals through 8) are printed, and any free space records and records 
no. yet printed are printed. See Figure 26. 

NAME COMPARE— When COMPARE is specified (NAME is a 
default), only the name of each miscompared catalog entry is listed. A 
miscompared catalog entry is one whose information is not identical to the 
information contained in the entry's copy in the catalog recovery area. A 
MISCOMPARE message is printed that identifies the most serious level of 
miscomparison. Within the "unsorted entries" group, miscompared records 
not yet printed out are printed. See Figure 27. 

DUMP COMPARE— When DUMP and COMPARE are specified, only 
the records (in dump format) of each miscompared catalog entry is listed. 
A miscompared catalog entry is one whose information is not identical to 
the information contained in the entry's copy in the catalog area. For each 
entry, the catalog recovery area copy is listed first, foUowed by the catalog 
entry, followed by a line that contains asterisks to identify each 
miscompared byte. Following each entry, a MISCOMPARE message is 
printed that identifies the most serious level of miscomparison. Within the 
"unsorted entries" group, miscompared records not yet printed out are 
printed in the dump format. See Figure 28. 

Note: As explained above, all MISCOMPARE messages result from a 
comparison between the catalog and the CRA if the comparison shows 
that the catalog and CRA records are not identical No inference is 
intended as to which is correct. You must make this determination yourself 
by looking at other mismatches in the same listing and by examining 
related records in the catalog or CRA. 

SEQUENTIALDUMP— When SEQUENTIALDUMP is specified, each 
record in the catalog recovery area is printed. The format of the output is 
the same as the DUMP NOCOMPARE format, except that the entries are 
not sorted into groups or alphabetical sequence. 

See 0S/VS2 Catalog Management Logic for a complete description of catalog 
recovery area record formats, catalog record formats, and relationships 
between catalog records. 



Job Control Language (JCL) for LISTCRA Jobs 

\ 



The job control language (JCL) statements that can be used to list catalog 
recovery areas are: 



//LISTCAT 


JOB 


//STEP1 


EXEC 


//STEPCAT 


DD 


//CATDD 


DD 


//CRADD1 


DD 


//CRADD2 


DD 


//OUTDD 


DD 


// 


VOL=; 


// 


DCB= 


//SYSPRINT 


DD 


//SYSIN 


DD 



PGM=IDCAMS 

DSN=YOURCAT , DISP=SHR 
DSN=YOURCAT , DI SP=OLD 
VOL=SER=333001 ,UNIT=3330,DISP=OLD 
VOL=SER=333002,UNIT=3a30,DISP=OLD 
DSN=LISTCRA . OUTPUT , UNIT=2400-3 , 
VOL=SER=TAPE 1 , LABEL= ( 1 , NL) , DI SP= ( NEW , KEEP ) , 
DCB=( RECFM=VBA, LRECL=1 25 , BLKSIZE=629 ) 
SYSOUT=A 

LISTCRA - 

COMPARE - 
DUMP - 

INFILE( CRADD1 ,CRADD2 ) - 
CATALOG ( YOURCAT/PASSWORD CATDD ) - 
MASTERPW( SECRET ) - 
OUTFILEC OUTDD) 
/* 

The JOB statement contains user and accounting information required for 
your installation. 

The EXEC statement identifies the program to be executed, IDCAMS (that 
is, the Access Method Services program). 

• STEPCAT DD, which allocates your catalog. This is only required if the 
COMPARE option is specified. The catalog must be open as a catalog 
before it can be opened as a data set through the DD card that so identifies 
it for the comparisons. 

• CATDD, which specifies the catalog to be opened as a data set and 
compared to the catalog recovery areas. This is only required if the 
COMPARE option is specified. 

• CRADDl, which specifies a volume whose catalog recovery area (CRA) is 
to be listed. 

• CRADD2, which specifies another volume whose CRA is to be listed. 

• OUTDD, which specifies an alternate output file, so that the LISTCRA 
output can be written onto an auxiliary storage device. The LISTCRA 
command's OUTFILE parameter points to the OUTDD DD statement. 
Only the LISTCRA output is written to the alternate output device. JCL 
statements, system messages, and job statistics are written to the 
SYSPRINT output device. 

- DSN=LISTCRA.OUTPUT specifies the name for the magnetic tape 
fUe. 

- UNIT= 2400-3 and VOL=?SER=TAPE10 specifies that the file is to be 
contained on magnetic tape volume TAPE 10. 

- LABEL=(1,NL) specifies that this is the first fUe on a nonlabeled tape. 
You can also use a standard-labeled tape by specifying LABEL=(1,SL). 
If subsequent job steps produce additional files of LISTCRA output on 
the same tape volume, you should increment the file number in each job 
step's LABEL subparameter (that is, LABEL=(2,NL) for the second 
job step, LABEL=(3,NL) for the third job step, etc.) 
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- DISP=(NEW,KEEP) specifies that this is a new tape file and is to be 
rewound when the job finishes. If a subsequent job step prints the tape, 
DISP=(NEW,PASS) shquld be specified. If your job step contains more 
than one LISTCRA command, DISP=(MOD,KEEP) or 
DISP=(MOD,PASS) can be used to concatenate all of the LISTCRA 
output in one sequential file. 

- DCB=(RECFM=VBA,LRECL=125,BLKSIZE=629) specifies that 
the LISTCRA output records are variable-length, blocked 5-to-l, and 
are preceded by an ANSI print-control character. 

• SYSPRINT DD, which is required for each Access Method Services job 
step. It identifies the output queue, SYSOUT=A, on which all LISTCRA 
output and system output messages are printed (unless the OUTFILE 
parameter and its associated DD statement is specified — see OUTDD 
above). 

Note: If you want all output to be written to an auxiliary storage device, 
replace 'OUTDD' with 'SYSPRINT' in the OUTDD DD statement and omit 
the SYSPRINT DD SYSOUT=A statement. 

• SYSIN DD, which specifies, with an asterisk (*), that the statements that 
follow are the input data statements. A '/*' terminates the input data 
statements. 

The LISTCRA command parameters shown above are common to the 
LISTCRA DUMP COMPARE example that foUows. Other LISTCRA 
parameters may be coded and the output that results is illustrated. 

COMPARE, which specifies that the CRA entries are to be compared with 
the catalog entries identified by the CATALOG parameter. Only those that 
miscompare will be Msted. \^ 

DUMP, which specifies that each hsted entry is to be printed in its entirety in 
both hexadecimal and character form. 

INFILE, which specifies the two DD statements, CRADDl and CRADD2^ 
which identify the two volumes whose CRA's are to be compared with the 
catalog entries and the miscomparing entries listed. 

CATALOG, which identifies the DD statement, CATDD, which identifies 
the catalog, YOURCAT, whose entries are to be compared with those in the 
CRAs. If the catalog is password protected, its master password, 
PASSWORD, is required. 

MASTERPW, which specifies the master password of the master catalog, 
SECRET, to enable the CRAs to be OPENed. 

OUTFILE, which points to the OUTDD DD statement. The OUTDD DD 
statement allocates an alternate output file for the LISTCRA output. 
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LISTCRA Output Listing 



If you want to print the LISTCRA output that is contained on an alternate 
output file, you can use the lEBGENER program. The following shows the 
JCL required to print the alternate output file, LISTCRA.OUTPUT, that was 
allocated previously: 

//PRINTOUT JOB 

//STEP1 EXEC PGM=IEBGENER 

//SYSUT1 DD DSN=LISTCRA. OUTPUT, UNIT=240 0-3, 

V0L=SER=TAPE1 ,LABEL=( 1 ,NL ) ,DISP=( OLD, KEEP ) , 
DCB=( RECFM=VBA,LRECL=125,BLKSIZE=629 ) 

//SYSUT2 DD SYS0UT=A 

//SYSPRINT DD SYS0UT=A 

//SYS IN DD DUMMY 

/* 

// 



When you specify LISTCRA without any parameters, each entryname, its 
volume(s), and the name and volume(s) of each related entry is listed. The 
same listing would result if the NAME and NOCOMPARE parameters were 
specified. 

You can use this type of listing to list the name of each catalog entry whose 
copy is in the catalog recovery area, and to determine the number of entries in 
each catalog recovery area. The total number of entries is an approximate 
size, in records, of the catalog recovery area. 
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LISTING OF CATALOG RECOVERY AREA FOR VOLUME — 333301 — VSAM ENTRIES 



VOL - 333301 

^^ CRAVOLRCD - 10/07/74 23:35:00 

yy-«^j^ F4DSCBVSAM - 10/07/74 23:35:00 

F4DSCBDUMP - 10/07/74 23:35:00 



^ ^ 



o- 



CLUS - AA.LISTCRA.ESDS 

DATA - TF41C9A0.VSAMDSET.DFD74280.T861DAD4.TF41C9A0 
DATA VOL - 
333301 

AIX - AA2.LR.ESDS 
DATA VOL - 

333301 
INDX VOL - 

333301 

AIX - AA1 .LR.ESDS 
DATA VOL - 

333301 
INDX VOL - 

333301 



0-* 

^■^ CLUS - AA.LISTCRA.KSDS <' E» 



PATH - AAU. LR.ESDS 
UPGD 



DATA - T5C55DD0.VSAMDSET.DFD74280.T861DB0A.T5C55DD0 
DATA VOL - 
333301 

INDX - T5C56E70.VSAMDSET.DFD74280.T861DB0A.T5C56E70 
INDX VOL - 
333301 



AIX - AA1 .LR.ESDS 



^ #11 



DATA - TCD41020.VSAMDSET.DFD74280.T861DB23.TCD41020 
DATA VOL - 
333301 

INDX - TCD41FO0.VSAMDSET.DFD7428O.T861DB23.TCD41F0O 
INDX VOL - 
333301 



yp '*' 



— o 



CLUS - AA.LISTCRA.ESDS 

PATH - AA1U. LR.ESDS 

PATH - AA1N. LR.ESDS 

CLUS - LR.MCKEYRNG.KSDS 

DATA - TF081480.VSAMDSET.DFD74280.T861DB0E.TFO81480 
DATA VOL - HIGH KEY 

333301 - C1C1C1C1C1C1C1C1C5F9 
333301 - C1C1C1C1C1C1C1C1E9E9 

INDX - TF082370.VSAMDSET.DFD74280.T861DB0E.TF082370 
INDX VOL - 

^ 333301 

333301 



LISTING OF CATALOG RECOVERY AREA FOR VOLUME -- 333301 — OTHER ENTRIES 



0— ^ 



UCAT - USEP.CAT2 

DATA VOL - 

333304 

NUMBER OF ENTRIES PROCE 

CLUS - 3 

DATA - 4 

AIX - 1 

INDX - 2 

PATH - 3 

VOL - 1 

UPGD - 1 

SUM - 15 



Figure 25 (Part 1 of 2). An Example of LISTCRA NAME NOCOMPARE Output 
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LISTCRA NAME NOCOMPARE Output Notes: 

1. Volume serial number 

2. Identifies the group that the following entries are within (in this case, VSAM Entries) 

3. The time stamps: 

CRAVOLRCD is the timestamp of the CRA volume record. It is updated only when the first catalog record and first 
CRA volume record are updated, after the CRA is opened when VSAM is running under OS/VS. (Note: If the volume is 
moved to a DOS/VS system and used there, the CRAVOLRCD timestamp is updated each time the catalog and CRA 
volume records are updated for a space allocation change.) 

F4DSCBySAM is a timestamp in the format-4 DSCB, and is updated in the same manner as the CRAVOLRCD 
timestamp. 

F4DSCBDUMP is a timestamp in the format-4 DSCB, and is updated in the same manner as the CRAVOLRCD 
timestamp. It is also updated whenever the OS/VS utility program lEHDASDR dumps the volume. 

4. VSAM entries are listed along with the entryname and volume(s) of each related entry. 

5. Paths are shown as related only to the entry that the path provides access to. A path that serves as an alias for a VSAM 
data set is listed with the data-set's entry. A path that shows the relationship of an alternate index to a base cluster is listed 
with the alternate-index's entry only. 

6. UPGD indicates that there are alternate indexes in the base-cluster's upgrade set. If you want to identify the indexes in 
the upgrade set, use the DUMP NOCOMPARE option. 

7. The high-key value of each key range is shown. 

8. SUM is the total number of catalog recovery area entries printed. 

Figure 25 (Part 2 of 2). An Example of LISTCRA NAME NOCOMPARE Output 
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LISTCRA DUMP Output Listing 



When you specify LISTCRA with the DUMP parameter, each record in the 
catalog recovery area is listed in dump format. In addition, the name and 
volumes of each indirectly related entry is also listed. The same listing would 
result if the DUMP and NOCOMPARE parameters were specified. 

When you specify LISTCRA SEQUENTIALDUMP, the same listing 
results — except that the records are listed in their entry-sequence within the 
catalog recovery area. 

You can use this type of listing to list the complete contents of each catalog 
entry whose copy is in the catalog recovery area, and to determine the exact 
number of entries and records in each catalog recovery area. 






VOL - 

|000009| 
0020 
0040 
0060 
0080 
OOAO 
OOCO 
OOEO 
0100 
0120 
0140 
0160 
0180 
01A0 



v:© 



LISTING OF CATALOG RECOVERY AREA FOR VOLUME 



333301 

0C <O0OOOC| 01F3F3F3 F3FOF100>(00093050 
00000000 00000000 00000000 lESblBDOO 
00000000 00000000 00000000 OOOOOOOO 
1152A820 00305020 09000032 E6O19BO0 
OOOOOOOO 2600003E OOOOOOOO OO0D85O0 
86000100 00378800 01000037 88000200 
05000037 88000600 00480800 07000037 
00378800 0B000037 88000C00 00378800 
88001000 00378800 11000037 88001200 
1500003E 88001600 003E8800 1700003E 
003E8800 IBObOOOO O8OO1CO0 OOOC0800 
08002000 003C0800 21000C00 005 186 ID 
46O0OCO0 0054861D B2050000 47000COO 
B23FOOOO 4C000C00 0058861D B23FOOO0 



2 oqy86iD 

7F tF3F3F3 



8A4E0000 



F3F0F100I 



OOOOOOOO 
13336DBF 
0100000E 
00378800 
88000800 
OD000037 
00378800 
88001800 
1D000018 
B1D60000 
0055861D 
50000C00 



OOOOOOOO 
BF380002 
85000200 
03000037 
00378800 
88000E00 
1300003E 
003E8800 
0800 1E00 
42000C00 
B2050000 
006086 ID 



OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
00000500 
000F8500 
88000400 
09000037 
00378800 
88001400 
1900003E 
00240800 
0052861D 
48000C00 
B79C,0000 



■^ 



333301 ~ VSAM ENTRIES 

OOOOOOOO l333301| v , 

OOOOOOOO EvJ. - 333301, 

00861DEE 

OOOOOOOO S .W 

03000037 

00378800 

88000A00 

0F000037 

003E8800' 

88001A00 

1F000030 

B1D60000 , . . . .0 

0057861D .'.. . 

2C1DB173 ) 6....... 



0— ♦ 



CLUS - KSDS01 

O OOOOE 00000017 01F3F3F3 F3F0F100 OOOE3050 
00201 OOOOOOOO OOOOOOOO OOOOOOOO C3O0A8O0 
0040 40404040 40404040 40404040 40404040 
0060 FFFFFFFF FF74280F OOOOOFOO OOOOOOOO 
0080 0200000C 02030000 12020400 00004401 
00A0| Q01A0006 C700001B OOOOOOOO OOOOOOOO 



5»6 8A4 



2 00986 tb 8A4E0OOO 
6C ID2E2C4 E2F0F140' 
40404040 40404040 
00070000 OOCOOOOO 
0006C400 00180006 
OOOOOOOO OOOOOOOO 



DATA - T188DOC0.VSAMDSET.DFD7428O.T861D99E.T188DOCO 



OOOOOD 
0020 
0040 
0060 
0080 
OOAO 
OOCO 
OOEO 
0100 
0120 
0140 
0160 



00000018 
OOOOOOOO 
C5E34BC4 
FFFFFFFF 
OOOOOOOf 
00620201 
00000300 
OOOOOOOO 
OOOOOOOO 
09F3F3F3 
0OO1O000 
00150000 



01F3F3F3 
OOOOOOOO 
C6C4F7F4 
FF74280F 
k900o0ff 
0000A902 
OOOOOOOO 
OOOOOOOO 
00000030 
F3F0F100 
00000014 
OOOOOOOO 



F3F0F100 
OOOOOOOO 
F2F8F04B 
OOOOOOOO 
FFFFFFFF 
02000068 
00000010 
OOOOOOOO 
OOOOOOOO 
00800100 
00010002 
OOOOOOOO 



OOOD3050 
C4O162O0 
E3F8F6F1 
20000000 
FFFFPFOO 
03010000 
OOOOOOOF 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
00000002 
OOOOOOOO 



2009861D 
8FE3F1F8 
C4F9F9C5 
22000000 
OOOOOOOO 
00440100 
F9000000 
01000000 
OOOOOOOO 
OOOOOOOO 
0OOOOOO1 
OOOOOOOO 



8A4E861D 
F8C4F0C3 
4BE3F1F8 
01000001 
06000000 
62608000 
OOOOOOOO 
OOOOOOOO 
000006C3 
00300000 
OOOOOOOO 
OOOOOOOO 



INDX - T188E190.VSAMDSET.DFD74280.T861D99E.T188E190 



OOOOOF 
0020 
0040 
0060 
0080 
OOAO 
OOCO 
OOEO 
0100 
0120 
0140 



00000019 
OOOOOOOO 
C5E34BC4 
FFFFFFFF 
OOFFFFFF 
00620201 
OOOOOOOO 
OOOOOOOO 
00002800 
FOF 10000 
00001400 



01F3F3F3 
OOOOOOOO 
C6C4F7F4 
FF74280F 
FFOOOOFF 
00006803 
00000200 
OOOOOOOO 
OOOOOOOO 
80010000 
01000200 



F3F0F100 
OOOOOOOO 
F2F8F04B 
OOOOOOOO 
FFFFFFFF 
01000000 
00000 1F9 
00000001 
OOOOOOOO 
OOOOOOOO 
01000200 



OOOF3O50 
C90157O0 
E3F8F6F1 
2000FFFF 
FFFFFFOO 
44010062 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
01000100 



200986 ID 
8FE3F1F8 
C4F9F9C5 
FFFFOOOO 
OOOOOOOO 
60000060 
OOOOOOOO 
OOOOOOOO 
0006C300 
28000000 
OOOOOOOO 



8A4E861D 
F8e5F1F9 
4BE3F1F8 
01000001 
05000000 
00010003 
OOOOOOOO 
OOOOOOOO 
00170327 
02000014 
0027FF00 



OOOOOOOO 
40404040 
40404040 
00000201 
C9000019 
OOOOOOOO 



99E20000 
F04BE5E2 
F8C4F0C3 
80000000 
OOOOOOOO 
60000000 
OOOOOOOO 
OOOOOOOO 
00001703 
00100000 
00002FFF 
OOOOOOOO 



99E20000 
F04BE5E2 
F8C5F1F9 
80000000 
COOOOOOO 
00140000 
OOOOOOOO 
OOOOOOOO 
30502009 
00140000 
OOOOOOOO 



OOOOOOOO 
40404040 
40FFFFFF 
00006024 
0006D900 
OOOOOOOO 



OOOOOOOO 
C1D4C4E2 
FOFFFFFF 
00000030 
00010100 
03001400 
OOOOOOOO 
OOOOOOOO 
27305020 
03000140 
0006E800 
OOOOOOOO 



OOOOOOOO 
C1D4C4E2 
FOFFFFFF 
00000028 
00010100 
00140000 
OOOOOOOO 
OOOOOOOO 
F3F3F3F3 
02000000 
OOOOOOOO 



.g3330TJ,, 



.C. . . (KSDS01 



PATH - PATH01 

000010 0000001A 
0020 OOOOOOOO 
0040 40404040 
0060 FFFFFFFF 
0080 0200000C 



01F3F3F3 F3F0F100 OO1OOOO0 
OOOOOOOO OOOOOOOO D90O98O0 
40404040 40404040 40404040 
FF74280F OOOOOFSO OOOOOOOO 
02030006 C3000017 0006C400 



000086 ID 8A4E0000 OOOOOOOO OOOOOOOO 
6CD7C1E3 C8F0F140 40404040 40404040 
40404040 40404040 40404040 40FFFFFF 
OOOOOOOO OOCOOOOO 00000201 00000602 
00180006 C9000019 OOOOOOOO OOOOOOOO 



333301 £..... + ,,.$,,,.,, 

D T188D0C0.VSAMDS 

ET.DFD74280.T861D99E.T188D0C0. . . 



333301 £ + . . .S 

i I T188E190.VSAMDS 

ET.DFD74280.T861D99E.T188E190. . . 



.C £..3333 



. R . . . ( PATH0 1 



Figure 26 (Part 1 of 2). An Example of LISTCRA DUMP NOCOMPARE Output 
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AIX - AIX01 
DATA VOL - 

333301 
INDX VOL - 

333301 



UPGD 



iy 01F3F3Fy F3F0F1C 
0# OOOOOOOP OOOOOOC 



000014 OOOOOOiy 01F3F3Fy F3F0F100 00143050 20O0861D 8A4E0000 00000000 00000000 
0020 00000 00» OOOOOOOP 0000000 E8004B00 31000000 00000200 OOOOCOOO 00000002 
0040 O1OOO; g4r000O1Ct:9t OOOOIEt PO 00000000 00000000 00000000 00000000 00000000 

DATA - TF081 480. VSAMDSET.DFD74280.T861DB0E.TF08 1480 



333301 i, + . 

Y 



"t) 



000038 
/ 0020 
0040 
0060 
0080 
OOAO 
OOCO 
OOEO 
0100 
0120 
0140 
0160 
0180 
01A0 
01C0 



00000048 
00000000 
C5E34BC4 
FFFFFFFF 
OOOOOOOO 
00620201 
00001400 
OOOOOOOO 
OOOOOOOO 
09F3F3F3 
0018000A 
00040003 
OOOOOOOO 
C1C6C100 
0000004F 



01F3F3F3 
OOOOOOOO 
C6C4F7F4 
FF742eOF 
500000FF 
00006803 
OOOOOOOO 
OOOOOOOO 
00000050 
F3FOF100 
C1C1C1C1 
00040001 
00002800 
0AC1C1C1 
FFOOOOOO 



F3F0F100 
OOOOOOOO 
F2F8F04B 
OOOOOOOO 
FFFFFFFF 
010000BD 
00000002 
OOOOOOOO 
OOOOOOOO 
00800100 
C1C1C1C1 
OOOOOOOO 
00005000 
C1C1C1C1 
OOOOOOOO 



00383050 
C401C500 
E3F8F6F1 
20000000 
FFFFFFOO 
03020000 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
C1C1000A 
000027FF 
00000200 
C1E9E900 
OOOOOOOO 



200986 ID 
8FE3C6F0 
C4C2F0C5 
06000000 
OOOOOOOO 
00440100 
50000000 
02000000 
OOOOOOOO 
OOOOOOOO 
C1C1C1C1 
03273050 
00140009 
14000100 
OOOOOOOO 



8A4E861D 
F8F1F4F8 
4BE3C6F0 
01000001 
06000000 
62608400 
OOOOOOOO 
OOOOOOOO 
000006C3 
00280000 
C1C1C1C1 
2009F3F3 
40001800 
03000500 
OOOOOOOO 



INDX - TF082370.VSAMDSET.DFD74280.T861DB0E.TF082370 



0000 3 A 
0020 
0040 
0060 
0080 
OOAO 
OOCO 
OOEO 
CI 00 
0120 
0140 
0160 
0180 



00000049 
OOOOOOOO 
C5E34BC4 
FFFFFFFF 
OOFFFFFF 
00620201 
00001400 
OOOOOOOO 
OOOOOOOO 
09F3F3F3 
00190000 
2009F3F3 
40001900 



01F3F3F3 
OOOOOOOO 
C6C4F7F4 
FF74280F 
FFOOOOFF 
00006803 
OOOOOOOO 
OOOOOOOO 
00000028 
F3FOF100 
00000014 
F3F3F0F1 
OOOOOOOO 



F3F0F100 
OOOOOOOO 
F2F8F04B 
OOOOOOOO 
FFFFFFFF 
010000A9 
00000002 
OOOOOOOO 
OOOOOOOO 
00800100 
00010003 
00004000 
OOOOOOOO 



003A3050 
C9018900 
E3F8F6F1 
2000FFFF 
FFFFFFOO 
03020000 
00000001 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 
00060003 
OOOOOOOO 
OOOOOOOO 



200986 ID 
8FE3C6F0 
C4C2F0C5 
FFFFOOOO 
OOOOOOOO 
00440100 
F9000000 
01000000 
OOOOOOOO 
OOOOOOOO 
00060001 
OOOOOOOO 
OOOOOOOO 



8A4E861D 
F8F2F3F7 
4BE3C6F0 
01000001 
06000000 
62600400 
OOOOOOOO 
OOOOOOOO 
000006C3 
00280000 
OOOOOOOO 
OOOOOOOO 
OOOOOOOO 



BOFOOOOO 
F04BE5E2 
F8F1F4F8 
80000000 
OOOOOOOO 
60000000 
OOOOOOOO 
OOOOOOOO 
00004703 
00020000 
C5F90014 
F3F3FOF1 
0AC1C1C1 
03000500 
OOOOOOOO 



BOFOOOOO 
F04BE5E2 
F8F2F3F7 
80000000 
COOOOOOO 
60000400 
OOOOOOOO 
OOOOOOOO 
00004703 
00020000 
0O0027FF 
00000200 
OOOOOOOO 



OOOOOOOO 
C1D4C4E2 
FOFFFFFF 
00000050 
00010100 
OAOOOAOO 
OOOOOOOO 
OOOOOOOO 
27305020 
14000140 
00010003 
00008001 
C1C1C1C1 
01000028 
OOOOOOOO 



OOOOOOOO 
C1D4C4E2 
FOFFFFFF 
00000028 
00010100 
OAOOOAOO 
OOOOOOOO 
OOOOOOOO 
27305020 
14000140 
03273050 
00140001 
OOOOOOOO 



333301 i. + ...0 

D.E. .TF081480.VSAMDS 

ET.DFD74280.T861DB0E.TF081480. . . 
i 



. 1333301 



AAAAAAAAAA. .AAAAAAAAE9 ..^€m 



. £ . J33^:^6^ .4r^ 



AFA..AAAAAAAAZZ. 



333301 £ + ...0 

I TF082370 . VSAMDS 

ET.DFD74280.T861DB0E.TF082370. . . 



.333301., 
..333301. 



LISTCRA DUMP NOCOIviPARE Output Notes: 

Note: When you specify SEQUENTIALDUMP, the same information is listed. The entries are not sorted according to type 
of entry, or according to alphanumeric-sequence of the entryname field. S>ee also note 7 below. 

1. The 3-byte CRA control interval number, in hexadecimal form. 

2. The 3-byte control interval number of the catalog record for which this is a copy, in hexadecimal form. 

3. The entrytype at offset X'2C' (decimal 44), a character that identifies the type of catalog entry being listed. 

4. A 44-byte field at offset X'31' (decimal 49) that contains the entry's entryname (padded with binary zeros), or a 8-byte 
field followed by 36 bytes of binary zero that contains the volume entry's volume serial number. 

5. The volume serial number of the recovery volume. 

6. A 2-byte displacement value. Printing is suppressed after the last line containing data is listed, even though all catalog 
records are 512 bytes long. 

7. As in the NAME NOCOMPARE output, the alternate index name and the fact that there is an upgrade set is given, along 
with the volume serial numbers of the alternate index's data and index components. (Note: If SEQUENTIALDUMP is 
specified, the information described with this note is not listed.) 

8. The first byte identifies the alternate index's data component and the next three bytes contain its catalog control interval 
number. 

9 The first byte identifies the alternate index's index component and the next three bytes contain its catalog control interval 
number.. 

10. Since there are two key ranges for this cluster, there are two volume information sets of fields in the cluster's data and 
index component entries. 

Figure 26 (Part 2 of 2). An Example of LISTCRA DUMP NOCOMPARE Output 



Appendix D: Interpreting LISTCRA Output Listings 503 



LISTCRA COMPARE Output Listing 



When you specify LISTCRA with the COMPARE parameter, each record in 
the catalog recovery area is compared to its original in the catalog. The name 
of each catalog entry that miscompares is Usted. A miscompared catalog entry 
is one whose information is not identical to the information contained in the 
entry's copy in the catalog recovery area. The same listing would result if the 
NAME and COMPARE parameters were specified. 

You can use this type of listing to determine the number of damaged entries 
in your catalog, and you can get an idea of the type of damage that occurred 
to each entry. You can issue the EXPORTRA and IMPORTRA commands to 
recover the catalog and make its damaged entries usable. 



LISTING OF CATALOG RECOVERY AREA FOR VOLUME — 333301 — VSAM ENTRIES 

£^ ►CATVOLRCD - 09/17/42 23:53:47 

^^ CRAVOLRCD - 10/07/74 23:35:00 

F4DSCBVSAM - 10/07/74 23:35:00 

F4DSCBDUMP - 10/07/74 23:35:00 

CLUS - LR. DELETED. ESDS 

* MISCOMPARES - CATALOG ENTRY HAS DIFFERENT NAME , 

CLUS - LR.MCHURBA.ESDS \ 

DATA - T73FEDA0.VSAMDSET.DFD74280.T861DAE1 .T73FEDA0 
DATA VOL - 
333301 



©- 



* MISCOMPARES - HIGH USED RBA 

CLUS - LR.MCKEYRNG.KSDS 

DATA - TF081 480. VSAMDSET.DFD74280.T861 OBOE. TF08 1480 
DATA VOL - HIGH KEY 

333301 - C1C1C1C1C1C1C1C1C5F9 
333301 - C1C1C1C1C1C1C1C1E9E9 

* MISCOMPARES - HIGH USED RBA 

INDX - TF082370.VSAMDSET.DFD74280.T861DB0E.TF082370 
INDX VOL - 
333301 
333301 

* MISCOMPARES - STATISTICS 

NUMBER OF ENTRIES PROCESSED 
CLUS - 23 
DATA - 18 
AIX - 8 
INDX - 11 
PATH - 5 
VOL - 1 
UPGD - 3 
SUM - 69 

IDC0665I NUMBER OF ENTRIES THAT MISCOMPARED IN THIS CRA - 3 

^V-*IDC0877I NUMBER OF RECORDS THAT MISCOMPARED IN THIS CRA - 4 

LISTCRA NAME COMPARE Output Notes: 

1. In addition to the timestamps described for the NAME NOCOMPARE output (noted previously), the timestamp in the 
catalog volume record, CATVOLRCD, is listed. CATVOLRCD is updated in the same manner as the CRAVOLRCD 
timestamp. 

2. The MISCOMPARES message always refers to the record listed above it. See "Regaining Access to Data" under "Catalog 
Recovery" in the chapter on Data Security and Protection for the cause and seriousness of this MISCOMPARES 
message. 

3. The number of records is sometimes larger than the number of entries, because an entry might consist of a catalog record 
and one or more extension records that failed to compare correctly. 



Figure 27. An Example of LISTCRA NAME COMPARE Output 
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USTCRA DUMP COMPARE Output Listing 



When you specify LISTCRA with the DUMP and COMPARE parameters, 
each record in the catalog recovery area is compared to its original in the 
catalog. Each catalog entry's copy in the catalog recovery area that 
miscompares is listed, followed by its original catalog entry (which is 
damaged), followed by asterisks to indicate each miscompared byte. 

You can use this type of listing to determine the exact damage that occurred 
to each entry. You might be able to correct some or all of the damage by 
using the ALTER command. You can issue the EXPORTRA and 
IMPORTRA commands to recover the catalog and make its damaged entries 
usable. 



LISTING OF CATALOG RECOVERY AREA FOR VOLUME 



VSAM ENTRIES 



LR.MCHURBA.ESDS 



000020 0000002C 01F3F3r3 F3F0F100 00203050 
CATRCD 0000002C 01F3F3F3 F3F0F100 00203050 

0020 00000000 00000000 00000000 C3O082O0 
00000000 00000000 00000000 03008200 

0040 40404040 40404040 40404040 40404040 
40404040 40404040 40404040 40404040 

0060 FFFFFFFF FF74280F OOOOOFOO 00000000 
FFFFFFFF FF74280F OOOOOFOO 00000000 

0080 002D0000 00000000 00000000 00000000 
002D0000 00000000 00000000 00000000 



200986 ID 8A4EOO00 00000000 00000000 
200986 ID 8A4E0000 OOOOOOOO 00000000 

6CD3D94B D4C3C8E4 D9C2C14B C5E2C4E2 
6CD3D94B D4C3C8E4 D9C2C14B C5E2C4E2 

40404040 40404040 40404040 40FFFFFF 
40404040 40404040 40404040 40FFFFFF 

OOOOOOOO 00020100 00004401 0006C400 
OOOOOOOO 00020100 00004401 0006C400 

OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 
OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 



.333301 £. 

.333301.. ..&. 



■4- Q 



.C. .. (LR.MCHURBA.ESDS 
.C. . . (LR.MCHURBA.ESDS 



DATA - T73FEDAO.VSAMDSET.DFD74280.T861DAE1.T73FEDA0 



000021 0000002D 01F3F3F3 F3F0F100 00213050 
CATRCD 0000002D 01F3F3F3 F3FOF100 00213050 

0020 OOOOOOOO OOOOOOOO OOOOOOOO C40 15700 
OOOOOOOO OOOOOOOO OOOOOOOO C4015700 

0040 C5E34BC4 C6C4F7F4 F2F8F04B E3F8F6F1 
C5E34BC4 C6C4F7F4 F2F8F04B E3F8F6F1 

0060 FFFFFFFF FF74280F OOOOOOOO 20000000 
FFFFFFFF FF74280F OOOOOOOO 20800000 

0080 OOOOOOOO 500000FF FFFFFFFF FFFFFFOO 
OOOOOOOO 500000FF FFFFFFFF FFFFFFOO 

OOAO 00620201 00006803 01000000 44010062 
00620201 00006803 01000000 44010062 



2009861D 8A4E861D AE2E0000 OOOOOOOO 
2009861D 8A4E861D AE2E0000 OOOOOOOO 

8FE4F7F3 C6C5C4C1 F04BE5E2 C1D4C4E2 
8FE4F7F3 C6C5C4C1 F04BE5E2 C1D4C4E2 

C4C1C5F1 4BE3F7F3 C6C5C4C1 FOFFFFFF 
C4C1C5F1 4BE3F7F3 C6C5C4C1 FOFFFFFF 

04000000 01000001 80000000 00000028 
04000000 01000001 80000006 00000028 

OOOOOOOO 05000000 OOOOOOOO 00010100 
OOOOOOOO 05000000 COOOOOOO 00010100 

60000060 OOOOOOOO OOOOOOOO 00140000 
60000060 OOOOOOOO OOOOOOOO 00140000 



• MISCOMPARES - HIGH USED RBA 



.333301 £..... + . 

.333301. ...S . + . 



.D T73FEDA0.VSAMDS 

.D T73FEDA0.VSAMDS 



ET.DFD74280.T861DAE1.T73FEDAO. 
ET.DFD74280.T861DAE1 .T73FEDA0. 



4--^ 



LISTCRA DUMP COMPARE Output Notes: 

1. The 3-byte CRA control interval number in hexadecimal form. 

2. Each pair of hexadecimal-data lines are the information in the catalog recovery area's copy of the catalog record, followed 
by the information in the catalog record, for the same displacement. 

3. Asterisks are printed below the bytes in which a miscompare exists and, in the left margin, the miscompared lines are 
flagged with a single asterisk. 

4. See "Regaining Access to Data" under "Catalog Recovery" in the chapter on Data Security and Protection for the cause 
and seriousness of this MISCOMPARES message. 

Figure 28. An Example of LISTCRA DUMP COMPARE Output 
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APPENDIX E: SAMPLE OUTPUT FROM CHKLIST 



Figure 29 shows the format of output from the CHKLIST command. 

For each checkpoint entry listed under "CHECKID," the other columns give 
dsname, ddname, unit, and volume information for each tape data set that 
was open at the time of the checkpoint. Asterisks under "UNIT" indicate an 
unrecognizable unit type. "VOLUME X OF Y IS CURRENT" indicates the 
volume sequence number of the volume mounted at the time of the 
checkpoint and the total number of volumes in the data set. Each volume's 
volume serial number is listed, and an asterisk indicates the volume mounted 
at the time of the checkpoint. 



CHKLIST INFILE(CHKPT) CHECKID(C0000001 C0000002) 

IDCAMS SYSTEM SERVICES TIME: 21:34:43 01/16/75 

OPEN TAPE DATA SET LIST FROM CHECKPOINT DATA SET - CHKPT DATASET 



CHECKID 
COOOOOOl 



DSNAME 



USER . TAPE . DATASETO 



USER . TAPE . DATASET 1 



DDNAME UNIT 

DDN2VS11 2400-7TRK 
DDN3VS11 2400-9TRK 



USER. TAPE. DAT ASET2 DDN4VS1 1 3400-7TRK 



VOLUMES 



VOLUME 
120001* 

VOLUME 
130001 

VOLUME 
140001* 



INDICATES CURRENT VOLUME 



1 IS CURRENT 



3 OF 
130002 



4 IS CURRENT 
130003* 130004 

1 IS CURRENT 



USER . TAPE . DATASET3 






DDNAME32 2400-9TRK VOLUME 
230001 
230006 



USER. TAPE. DAT ASET4 DDNAME42 2400-9TRK 



VOLUME 
240001 
240006 
240011 
240016 
240021 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 

IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 

Figure 29. An Example of CHKLIST Output 



8 OF 8 IS CURRENT 

230002 230003 230004 230005 

230007 230008* 

20 OF 24 IS CURRENT 

240002 240003 240004 240005 

240007 240008 240009 240010 

240012 240013 240014 240015 

240017 240018 240019 240020* 

240022 240023 240024 
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APPENDIX F: COMMA^fD REFERENCE 
SUMMARY 



This section shows the format of each Access Method Services functional 
command, parameter abbreviation, and defaults. The commands are grouped 
together to allow you to remove these pages and use them for a quick 
reference. 



y 



Appendix F: Command Reference Summary 509 



I 



ALTER — modify attributes of a data set cataloged in a VSAM catalog 



, ^Parameters 


Abbrev. 


ALTER 





entryname [ / password ] 


— 


[ADDVOLUMES( volser [ b volser ...])] 


AVOL 


[AiTEMPTS( number ) ] 


ATT 


[AUTHORIZATIONC entrypoint [ h string ])] 


AUTH 


[BUFFERSPACEC size )] 


BUFSP, BUFSPC 


[CODE( code )] 


— 


[CON'IROLPW( password )] 


CTLPW 


[DESTAGEWAIT | NODESTAGEWAIT] 


DSTGW NDSTGW 


[EMPTY 1 NOEMPTY] 


EMP NEMP 


[ERASE 1 NOERASE] 


ERAS NERAS 


[EXCEFI'IONEXIT( entrypoint )] 


EEXT 


[nLE( dname )] 


— 


[FREESPACEC Cl-percent [fe CA-percent])] 


FSPC 


[INHIBIT 1 UNINHIBIT] 


INH UNINH 


[KEYS( length b offset )] 


— 


[MAS1'ERPW( password )] 


MRPW 


[NEWNAMEC newname )] 


NEWNM 


[NULLIFY( 


NULL 


[AUTHORIZATIONCMODULE 1 STRING)] 


AUTH MDLE 




STRG 


[CODE] 


— 


[CONTROLPW] 


CTLPW 


[EXCEFllONEXm 


EEXT 


[MASIERPW] 


MRPW 


[OWNER] 


— 


[READPW] 


RDPW 


[RETENTION] 


RETN 


[UPDATEPW])] 


UPDPW 


[OWNER( ownerid )] 


— 


[READPW( password )] 


RDPW 


[RECORDSIZE( average b maximum )] 


RECSZ 


[REMOVEVOLUMESC voiser [b volser ...])] 


RVOL 


[SCRATCH 1 NOSCRATCH] 


SCR NSCR 


[SHAREOPTIONSC crossregion [b cros5s;'5tem ])] 


SHR 


[STAGE I BIND 1 CYLINDERFAULT] 


CYLF 


[TO( date ) I FOR( days )] 





[UNIQUEKEY | NONUNIQUEKEY] 


UNQK NUNQK 


[UPDATE 1 NOUPDATE] 


UPD NUPD 


[UPDATEPW( password )] 


UPDPW 


[UPGRADE 1 NOUPGRADE] 


UPG NUPG 


[WRITECHECK 1 NOWRITECHECK] 


WCK NWCK 


[CATALOG( catname [ / password ])] 


CAT 
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BLDINDEX — build alternate indexes for existing VSAM clusters 



Parameters 


Abbrev. 


BLDINDEX 

{INFILE( dname [/ password ]) | 
INDATASET( entry name [/ password])} 
{OUTFILEC dname [/ password ] 

[b dname [/ password ]... ]) I 
OUTDATASET( entry name [/ password] 
[b entry name [/ password]...])] 
[CATALOG( catname [/ password ])] 
[EXTERNALSORT | INTERNALSORT] 
[WORKFILES( dname b dname )] 


BIX 
IHLE 
IDS 
OHLE 

ODS 

CAT 

ESORT ISORT 

WFILE 



CHKLIST — identify tape volumes mounted when a checkpoint was taken 



Parameters 


Abbrev. 


CHKLIST 

INFILE( dname ) 
[CHECKIDC checkid ...)] 
[OUTFILEC dname )] 


CKLST 

IHLE 

CHKID 

OFILE 



CNVTCAT— convert OS catalog entries into OS/VS2 VSAM catalog entries 



Parameters 


Abbrev. 


CNVTCAT 


CNVTC 


{INFILE( dname ) I INDATASET( entryname )} 


IHLE IDS 


[CATALOG( catname [/ password ])] 


CAT 


[CVOLEQUATES({ catname b( volser 


CVEQU 


[b voher ...]))[b( camame ...)...])] 




[LIST 1 NOLIST] 


— NLIST 


[MASTERCATALOG( catname [/ password ])] 


MCAT 



DEFINE ALIAS — define an alternate name for a user catalog or a nonVSAM 
data set 



Parameters 


Abbrev. 


DEFINE 
ALIAS 
(NAME( aliasname ) 
RELATE( entryname ) ) 

[CATALOG( catname [/ password ])] 


DEF 

REL 
CAT 
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DEFINE ALTERNATEINDEX— define a VSAM catalog entry for an 
alternate Index 



Parameters 


Abbrev. 


DEFINE ALTERNATEINDEX 


DEF AIX 


(NAME( entryname ) 


— 


RELATE( entryname [/ password ]) 


REL 


{CYLINDERS^ primary [ fe secondary ]) | 


CYL 


RECORDS^ primary [ fe secondary ]) | 


REG 


TRACKS^ primary [b secondary ])J 


TRK 


VOLUMES2( yolser [b vo/j^r ... 1) 


VOL 


[ATTEMPTS( number \ 2)] 


ATT 


[AUTHORIZATION( entrypoint [b Jfrmg ])] 


AUTH 


[BUFFERSPACEC size )] 


BUFSP, BUFSPC 


[CODEC corfe )] 


— 


[CONTROLIN I ERVALSIZE( size )] 


CISZ, CNVSZ 


[CONTROLPWC password )1 


CTLPW 


[DESTAGEWAIT t NODESTAGEWAIT] 


DSTGW NDSTGW 


[ERASE 1 NOERASE] 


ERAS NERAS 


[EXCEPTIONEXITC entrypoint )] 


EEXT 


[FILE( dname )] 


— 


[FREESPACEC Cl-percent [b Cy4-/?ercenm 0)1 


FSPC 


[IMBED 1 NOIMBED] 


IMBD NIMBD 


[KEYRANGES(( lowkey b A/g/jite;^ ) 


KRNG 


[( lowkey b /wgA/te/ )...])] 




[KEYSi length h offset |640)] 


— 


[MASTERPW( password )] 


MRPW 


[MODELC entryname [/ password ] 


— 


[b cat name [/ password ] ])] 




[ORDERED 1 UNORDERED] 


ORD UNORD 


[OWNERC ownerid )] 


— 


[READPW( password )] 


RDPW 


[RECORDSIZE( average b maximum \ 


RECSZ 


4086 32600)] 




[REPLICATE 1 NOREPLICATE] 


REPL NREPL 


[REUSE 1 NOREUSE] 


RUS NRUS 


[SHAREOPTIONSC crossregion 


SHR 


[b crosssystem ] 1 1 3)] 




[SPEED 1 RECOVERY] 


— RCVY 


[STAGE 1 BIND | CYLINDERFAULT] 


CYLF 


[TO( date ) | FOR( days )] 





[UNIQUE 1 SUBALLOCATION] 


UNQ SUBAL 


[UNIQUEKEY | NONUNIQUEKEY] 


UNQK NUNQK 


[UPDATEPW( password )] 


UPDPW 


[UPGRADE 1 NOUPGRADE] 


UPG NUPG 


[WRITECHECK | NOWRITECHECK] ) 


WCK NWCK 



(Continued) 
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DEFINE ALTERNATEINDEX (Continued) 



Parameters 


Abbrev. 


[DATA 


— 


([ATTEMPTS( number )] 


ATT 


[AUTHORIZATION( entrypoint [fe string ])] 


AUTH 


[BUFFERSPACE( size )] 


BUFSP, BUFSPC 


[CODEC code )] 


— 


[CONTROLINTERVALSIZE( size )] 


CISZ, CNVSZ 


[CONTROLPW( password )] 


CTLPW 


[CYLINDERS( primary [h secondary ]) | 


CYL 


RECORDS( primary [b secondary ]) | 


REC 


TRACKS( primary [b secondary ])] 


TRK 


[DESTAGEWAIT | NODESTAGEWAIT] 


DSTGW NDSTGW 


[ERASE 1 NOERASE] 


ERAS NERAS 


[EXCEPTIONEXIK entrypoint )] 


EEXT 


[FILE( dname )] 


— 


[FREESPACEC Cl-percent [b CA-percent ])] 


FSPC 


[KEYRANGES(( /ow^e;' b /i/g/jJtej ) 
[( lowkey b highkey )... ])] 


KRNG 


[KEYS( fe«gf/i b o//j^/ )] 


— 


[MASTERPWC password )] 


MRFW 


[MODEL( entryname [/ password ] 
[b catname [/ password ]])] 


— 


[NAME( entryname )] 


— 


[ORDERED 1 UNORDERED] 


ORD UNORD 


[OWNER( o»v«erW )] 


— 


[READPW( password )] 


RDPW 


[RECORDSIZE( average b maximum )] 


RECSZ 


[REUSE INOREUSE] 


RUS NRUS 


[SHAREOFI'lONSC crossregion [b crowj^'j/em ])] 


SHR 


[SPEED 1 RECOVERY] 


— RCVY 


[STAGE I BIND | CYLINDERFAULT] 


CYLF 


[UNIQUE 1 SUBALLOCATION] 


UNQ SUBAL 


[UNIQUEKEY 1 NONUNIQUEKEY] 


UNQK NUNQK 


[UPDATEPWC password )] 


UPDPW 


[VOLUMES( vo/5er [b volser ...])] 


VOL 


[WRITECHECK ! NOWRITECHECK] )] 


WCK NWCK 


[INDEX 


TV 


([ATTEMPTSC number )] 


ATT 


[AUTHORIZATION! entrypoint [b srr/Vjg ])] 


AUTH 


[CODEC code )] 


— 


[CONTROLINTERVALSIZEC size )] 


CISZ, CNVSZ 


[CONTROLPW( password )] 


CTLPW 


[CYLINDERS! primarv [b secondary ]) | 


CYL 


RECORDS! primary [b secondary ]) | 


REC 


TRACKS! primary [b secondary ])] 


TRK 


[DESTAGEWAIT | NODESTAGEWAIT] 


DSTGW NDSTGW 


[EXCEPTIONEXIT! entrypoint )] 


EEXT 


[FILE! rfnawie )] 


— 


[IMBED 1 NOIMBED] 


IMBD NIMBD 



(Continued) 
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DEFINE ALTERNATEINDEX (Continued) 



Parameters 


Abbrev. 


[MASTERPW( password )] 


MRPW 


[MODEL( entryname [/ password ] 


— 


[b catname [/ password ]])] 




[NAME( entryname )] 


— 


[ORDERED 1 UNORDERED] 


ORD UNORD 


[OWNER( ownerid )] 


— 


[READPW( password )] 


RDPW 


[REPLICATE 1 NOREPLICATE] 


REPL NREPL 


[REUSE 1 NOREUSE] 


RUS NRUS 


[SHAREOFIIONS( crossregion [b crosssystem ])] 


SHR 


[STAGE 1 BIND 1 CYLINDERFAULT] 


CYLF 


[UNIQUE 1 SUBALLOCATION] 


UNQ SUBAL 


[UPDATEPW( password )J 


UPDPW 


[VOLUMES( voher [b volser ..,])] 


VOL 


[WRITECHECK | NOWRITECHECK] )] 


WCK NWCK 


[CATALOG( catname [/ password ])] 


CAT 



1 CYLINDERS, RECORDS, or TRACKS must be specified either as a 
parameter of ALTERNATEINDEX, as a parameter of DATA, or as a 
parameter of both DATA and INDEX if MODEL is not specified. 

^VOLUMES must be specified as a parameter of ALTERNATEINDEX or 
as a parameter of both DATA and INDEX if MODEL is not specified. 
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DEFINE CLUSTER— define a VSAM catalog entiy for 


a VSAM duster 


Parameters 


Abbrev. 


DEFINE CLUSTER 


DEF CL 


(NAME( entryname ) 


— 


{CYLINDERS^ primary {h secondary ]) | 


CYL 


RECORDSi( primary [b secondary ]) | 


REC 


TRACKSH primary [b secondary ])} 


TRK 


VOLUMES2( volser [b voher ... ]) 


VOL 


[ATTEMPTSC number I 2 )] 


ATT 


[AUTHORIZATION( entrypoint [b 5/rmg ])] 


AUTH 


[BUFFERSPACE( size )] 


BUFSP, BUFSPC 


[CODEC code )] 


— 


[CONTROLINTERVALSIZE( 5/2e )] 


CISZ, CNVSZ 


[CONTROLPW( password )] 


CTLPW 


[DESTAGEWAIT | NODESTAGEWAIT] 


DSTGW NDSTGW 


[ERASE 1 NOERASE] 


ERAS NERAS 


[EXCEPTIONEXITC entrypoint )] 


EEXT 


[FILEC dname )] 


— 


[FREESPACE3(CI- percent 


FSPC 


[b CA- percent ] 1 0)] 




[IMBED 1 NOIMBED]3 


IMBD NIMBD 


[INDEXED 1 NONINDEXED I NUMBERED] 


IXD NIXD NUMD 


[KEYRANGES3(( hwkey b highkey ) 


KRNG 


[( hwkey b highkey )...])] 




[KEYS3( /e«gr/i bo/yieH64 0)] 


— 


[MASTERPW( password )] 


MRPW 


[MODEL( entryname [/ password ] 


— 


[b catname [/ password ]])] 




[ORDERED 1 UNORDERED] 


ORD UNORD 


[OWNERC owner/f/ )] 




[READPW( password )] 


RDPW 


[RECORDSIZE4( average b maximum )] 


RECSZ 


[REPLICATE 1 NOREPLICATE]3 


REPL NREPL 


[REUSE 1 NOREUSE] 


RUS NRUS 


[SHAREOPTIONS( crossregion 


SHR 


[b cr(?5:?5>'srej?i ] ! 1 3)] 




[SPANNED 1 NONSPANNED] 


SPND NSPND 


[SPEED ! RECOVERY] 


RCVY 


[STAGE 1 BIND | CYLINDERFAULT] 


CYLF 


[TO( date ) | FOR( days )] 





[UNIQUE I SUBALLOCATION] 


UNQ SUBAL 


[UPDATEPW( password )] 


UPDPW 


[WRITECHECK | NOWRITECHECK] ) 


WCK NWCK 


[DATA 





([ATTEMPTS( number )] 


ATT 


[AUTHORIZATION( entrypoint [h string ])] 


AUTH 


[BUFFERSPACE( size )] 


BUFSP, BUFSPC 


[CODEC code )] 


— 


[CONTROLINTERVALSIZE( size )] 


CISZ, CNVSZ 


[CONTROLPW( password )] 


CTLPW 



(Continued) 
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DEFINE CLUSTER (Continued) 



Parameters 


Abbrev. 


[CYLINDERSC primary [b secondary ]) | 


CYL 


RECORDS( primary [fe secondary ]) | 


REC 


TRACKS( primary [b secondary ])] 


TRK 


[DESTAGEWAIT | NODESTAGEWAIT] 


DSTGW NDSTGW 


[ERASE 1 NOERASE] 


ERAS NERAS 


[EXCEPTIONEXrrC entrypoint )] 


EEXT 


[FILE( dname )] 


— 


[FREESPACE3(CI- percent [b CA- percent 1)] 


FSPC 


[KEYRANGES3(( /oM'ite>' \> highkey ) 


KRNG 


[( lowkey b highkey )...])] 




[KEYS^C /e«gr/t b o//jer )] 


— 


[MASl'ERPWC password )] 


MRPW 


[MODEL( entry name [/ password ] 


— 


[b catname [/ password ]])] 




[NAME( entryname )] 


— 


[ORDERED 1 UNORDERED] 


ORD UNORD 


[OWNER( ow/jmrf )] 


— 


[READPW( password )] 


RDPW 


[RECORDSIZE( average b maximum )] 


RECSZ 


[REUSE 1 NOREUSE] 


RUS NRUS 


[SHAREOPTIONS( crossregion [b crosssystem ])] 


SHR 


[SPANNED 1 NONSPANNED] 


SPND NSPND 


[SPEED 1 RECOVERY] 


— RCVY 


[STAGE I BIND | CYLINDERFAULT] 


CYLF 


[UNIQUE 1 SUBALLOCATION] 


UNQ SUBAL 


[UPDATEPW( password )] 


UPDPW 


[VOLUMESC volser [b vo/ser ...])] 


VOL 


[WRII ECHECK 1 NOWRITECHECK] )] 


WCK NWCK 


[INDEX 3 


IX 


([ATi'EMPTSC number )] 


ATT 


[AUTHORIZATION( entrypoint [b string ])] 


AUTH 


[CODE( code )] 


— 


[CONTROLINTERVALSIZE( size )] 


CISZ, CNVSZ 


[CONTROLPW( password )] 


CTLPW 


[CYLINDERSC primary [b secondary ]) | 


CYL 


RECORDS! primary [b secondary ]) I 


REC 


TRACKSC primary [b secondary ])] 


TRK 


[DESTAGEWAIT | NODESTAGEWAIT] 


DSTGW NDSTGW 


[EXCEPTIONEXrr( entrypoint )] 


EEXT 


[FILE( rfrtame )] 


— 


[IMBED 1 NOIMBED]3 


IMBD NIMBD 


[MASTERPW( password )] 


MRPW 


[MODEL( entryname [/ password ] 


— 


[b catname [/ password ]])] 




[NAME( entryname )] 


— 


[ORDERED 1 UNORDERED] 


ORD UNORD 


[OWNER( owner/V/ )] 


— 


[READPW( password )] 


RDPW 


[REPLICATE i NOREPLICATE]3 


REPL NREPL 



(Continued) 
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DEFINE CLUSTER (Continued) 



Parameters 


Abbrev. 


[REUSE 1 NOREUSE] 


RUS NRUS 


[SHAREOPTIONS( crossregion [b crosssystem ])] 


SHR 


[STAGE 1 BIND | CYLINDERFAULT] 


CYLF 


[UNIQUE 1 SUBALLOCATION] 


UNQ SUBAL 


[UPDATEPW( password )] 


UPDPW 


[VOLUMES( volser [ fe volser ...])] 


VOL 


[WRITECHECK j NOWRITECHECK] )] 


WCK NWCK 


[CATALOG( catnameU password])] 


CAT 



1 CYLINDERS, RECORDS, or TRACKS must be specified either as a 
parameter of CLUSTER, as a parameter of DATA, or as a parameter of 
both DATA and INDEX if MODEL is not specified. 

^VOLUMES must be specified as a parameter of CLUSTER or as a 
parameter of both DATA and INDEX if MODEL is not specified. 

3 Can only be specified for a key-sequenced cluster, 

^When SPANNED is specified, the default is RECORDSIZE ( 4086 
32600 ). Otherwise, the defauU is RECORDSIZE ( 4089 4089 ). 

DEFINE GENERATIONDATAGROUP— create a catalog entry for a 
generation data group 



Parameters 


Abbrev. 


DEFINE GENERATIONDATAGROUP 

'{NAMEt enfryname ) 
LIMIT( limit ) 
[EMPTY 1 NOEMPTY] 
[OWNER( ownerid )] 
[SCRATCH 1 NOSCRATCH] 
[TO( date ) I FOR( days )] ) 
[CAT ALOG( catnameU password])]' 


DEFGDG 

LIM 

EMP NEMP 

SCR NSCR 
CAT 



DEFINE NONVSAM— define a VSAM catalog entry for a nonVSAM data set 



Parameters 


Abbrev. 


DEFINE NONVSAM 

(NAME( entryname ) 

DEVICETVPESC devtype [b devtype ...]) 

VOLUMES( wiser [b volser ...]) 

[FILESEQUENCENUMBERS( number 
[b number ...])] 

[OWNER( ownerid )] 

[TO{ date )\¥OK( days)] ) 

[CATALOG(cama/ne [/ password])] 


DEF NVSAM 

DEVT 

VOL 

FSEQN 

CAT 
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DEFINE PAGESPACE— define a VSAM catalog entry for a page space 



Parameters 


Abbrev. 


DEFINE PAGESPACE 


DEF PGSPC 


(NAMEi entryname ) 


— 


{CYLINDERS( /^n/nary ) I 


CYL 


RECORDS(/»nmar)' ) I 


REC 


TRACKSi primary )} 


TRK 


VOLUME( volser ) 


VOL 


[ATTEMPTS( number | 2)] 


ATT 


[AUTHORIZATION( enttypoint [b string ])] 


AUTH 


[CODE( code )] 


— 


[CONTROLPW password )] 


CTLPW 


[FILE( dname )] 


— 


[MASTERPW( password )] 


MRPW 


[MODEL( entryname [/ password ] 


— 


[h catname [/ password]])] 




[OWNER( ownerid )] 


— 


[READPW( password )1 


RDPW 


[SWAPINOSWAP] 


— NSW AP 


[TCK date ) I FOR( days )] 





[UNIQUE 1 SUBALLOCATION] 


UNQ SUBAL 


[UPDATEPWC password )]) 


UPDPW 


[CATALOG( catname [/ password ])1 


CAT 



DEFINE PATH— define a relationstup between an alternate index and Its base 
chE^er 



Parameters 


Abbrev. 


DEFINE PATH 


DEF — 


(NAME( entryname ) 


— 


PATHENTRY( entryname [/ password ]) 


PENT 


[ATTEM¥TS( number |2)] 


ATT 


[AUTHORIZATIONC enttypoint [h string ])] 


AUTH 


[CODEC code )] 


__ 


[COKTROhPWi password )] 


CTLPW 


[FILE( dname )] 


— 


[MASTERPWC password )] 


MRPW 


[MODEL( entryname [/ password ] 


— 


[h catname [/ password ]])] 




[OWNER( ownerid )] 


— 


[READPW( password )] 


RDPW 


[TOi date )\FOK{ days )] 





[UPDATE 1 NOUPDATE] 


UPD NUPD 


[UPDATEPW( password )] ) 


UPDPW 


[CATALOG! catname [/ password ])] 


CAT 
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DEFINE SPACE— define a VSAM data space 



Parameters 


Abbrev. 


DEFINE SPACE 


DEF SPC 


( { CANDIDATE | 


CAN 


CYLINDERS( primary [h secondary ]) | 


CYL 


RECORDS( primary [t> secondary ]) 


REC 


t)RECORDSIZE( average h maximum ) | 


RECSZ 


TRACKS( primary [b secondary ])} 


TRK 


VOLUMES( volser [h volser ... ]) 


VOL 


[FILE( dname )] ) 


— 


[CATALOG( catname [/ password^ 


CAT 
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DEFINE USERCATALOG — Create a VSAM user catalog 



Parameters 


Abbrev. 


DEFINE USERCATALOG 1 MASTERCATALOG 


DEF UCAT MCAT 


(NAME( entryname ) 


— 


{CYLINDERSC primary [h secondary ]) 1 


CYL 


RECORDSC primary [fe secondary ]) | 


REG 


TRACKS( primary [b secondary ])} 


TRK 


VOLUMEC vofaer ) 


VOL 


[ATTEMPTSK numfter 12)] 


ATT 


[AUTHORIZATION( entrypoint [fe string ])] 


AUTH 


[BUFFERSPACEC s/ze |3072)] 


BUFSP, BUFSPC 


[CODEC code)] 


— ■ . 


[CONTROLPW(/ja5sworrf )] 


CTLPW 


[DESTAGEWAIT | NODESTAGEWAIT] 


DSTGW NDSTGW 


[FILE( dname )] 


— 


[MAS'IERPW( password )] 


MRPW 


[MODEL( entryname [/ password ] 


— 


[b catname [/ password ]])] 




[OWNER( ownerid )] 


— 


[READPWC password )] 


RDPW 


[RECOVERABLE | NOTRECOVERABLE] 


RVBL NRVBL 


[TO( date ) I FORC days )] 





[UPDATEPW( password )] 


UPDPW 


[WRITECHECK I NOWRITECHECK] ) 


WCK NWCK 


[DATA 


__ 


([BUFFERSPACE( size )] 


BUFSP, BUFSPC 


[CYLINDERSC primary [h secondary ]) | 


CYL 


WECORDSi primary [h secondary ]) | 


REG 


TRACKSC primary [h secondary ])] 


TRK 


[DESTAGEWAIT | NODESTAGEWAIT] 


DSTGW NDSTGW 


[RECOVERABLE | NOTRECOVERABLE] 


RVBL NRVBL 


[WRITECHECK 1 NOWRirECHECK] )] 


WGK NWGK 


[INDEX 


IX 


( [CYLINDERSC primary ) | 


GYL 


RECORDS( primary ) | 


REG 


TRACKSC primary )] 


TRK 


[DESTAGEWAIT | NODESTAGEWAIT] 


DSTGW NDSTGW 


[WRITECHECK I NOWRII ECHECK] )] 


WCK NWGK 


[CATALOGC mastercatname [ password ])] 


GAT 



/ 
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DEL£TE~HleIete entries from a VSAM catalog 



Parameters 


Abbrev. 


DELETE 


DEL 


( entry name [/ password ] 


— 


tb entry name [/ password ]...]) 




[ALIAS 1 


— 


ALTERNATEINDEX I 


AIX 


CLUSTER 1 


CL 


GENERATIONDATAGROUP I 


GDG 


NONVSAM 1 


NVSAM 


PAGESPACE 1 


PGSPC 


PATHI 


— 


SPACEi 1 


SPC 


USERCATALOGi] 


UCAT 


[ERASE INOERASE] 


ERAS NERAS 


[FILE( dname )] 


— 


[FORCE 1 NOFORCE] 


FRC NFRC 


[PURGE 1 NOPURGE] 


PRO NPRG 


[SCRATCH 1 NOSCRATCH] 


SCR NSCR 


[CATALOGC catname [/ password])] 


CAT 



^ When you delete a data space or catalog, you cannot delete any other 
type of entry. You must identify the type of entry to be deleted, by 
specifying SPACE or USERCATALOG. 

EXPORT— discomiect a VSAM user catalog 



Parameters 


Abbrev. 


EXPORT 

usercatname [/ password ] 
DISCONNECT 


EXP 
DCON 



EXPORT — copy a VSAM cluster or altemate index, together with its catalog 
entries, to a sequential data set 



Parameters 


Abbrev. 


EXPORT 


EXP 


entryname [/ password ] 


— 


{OUTFILEC dname ) | OUTDATASET( entryname)] 


OHLE CDS 


[ERASE 1 NOERASE] 


ERAS NERAS 


[INFILE( dname )] 


IFILE 


[INHIBITSOURCE I NOINHIBITSOURCE] 


INHS NINHS 


[INHIBITTARGET I NOINHIBITTARGET] 


INHT NINHT 


[PURGE 1 NOPURGE] 


PRG NPRG 


[TEMPORARY I PERMANENT] 


TEMP PERM 
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EXPORTRA— copy catalog entries from the Catalog Recovery Area (CRA) 



Parameters 


Abbrev. 


EXPORTRA 


XPRA 


OUTFILE( dname ) 


OFILE 


CRA( 


— 


( dnamel 




{ALL[bINFILE( dnamel )] I 


— IFILE 


ENTRIES( 


ENT 


( entryname [b dname3 ]) 




[( entryname [fe dnameS ])...]) | 




NONE}) 


— 


[( dnamel ...)...]) 




[FORCE 1 NOFORCE] 


FRC NFRC 


[MASTERPWC password )] 


MRPW 



IMPORT— -coraiect a VSAM user catalog 



. Parameters 


■ ' ! 
Abbrev. . 


IMPORT 
CONNECT 

OBJECTSii usercatname 

DEVICETYPE( devtype ) 

VOLUMES( vo/^er ))) 
[CATALOG( mastercatname [/ password ])] 


IMP 

CON 

OBJ 

DEVT 

VOL 

CAT 



IMPORT — restore a VSAM cluster or attentate index from a portable data set 
treated by the EXPORT command 



Parameters 


Abbrev. 


IMPORT 


IMP 


{INFILE( dname ) | INDATASET( en/ry/iame )} 


IFILE IDS 


{OUTFILEC dname [/ password ]) | 


OFILE 


OUTDATASET( entryname [/ password])] 
[ERASE INOERASE] 


ops 

ERAS>JERAS 


[INTOEMPTY] 


lEMPTY 


[OBJECTS(( entryname 


OBJ 


[FILE( dname )] 


__ 


[KEYRANGES(( lowkey h highkey ) 
[( lowkey b highkey )...])] 


KRNG 


[NEWfiAME( newwame )] 


NEWNM 


[ORDERED 1 UNORDERED] 


ORDUNORD 


[VOLUMES( volser [b volser ...])] ) 


VOL 


[{ entryname ...'\...'\)'\ 




[PURGE 1 NOPURGE] 


PRGNPRG 


[SAVRAC 1 NOSAVRAC] 





[CATALOG( catname U password])] 


CAT 
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EXECUTION CONTROL COMMANDS 
IF-THEN-ELSE Command Sequence 



Parameters 


Abbrev. 


IF 
{LASTCC 1 MAXCC } [b ] comparand [fe] number 
THEN[b command \ 
DO 

command set 
END] 

[ELSE[b command | 
DO 
command set 

END]] 





FARM Command 



Parameters 



Abbrev. 



FARM 

[TEST( 
{[TRACE] 

[AREAS( areaid [b areaid ...])] 
[FULL(( dumpid [b countl [b count2 ]]) 

[( dumpid ...)...])] I 
OFF} )] 
[GRAPHICS(CHAIN( chain ) | TABLE( mname ))] 
[MARGINS( leftmargin b rightmargin )] 



SET Command 



Parameters 


Abbrev. 


SET 
{MAXCC 1 LASTCCltb] = [hhumber 
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APPENDIX G: INVOKING ACCESS METHOD 
SERVICES FROM A PROBLEM PROGRAM 



Access Method Services can be invoked by a problem program through the 
use of the ATTACH, LINK, or LOAD and CALL macro instructions. 

The dynamic invocation of Access Method Services enables respecification of 
selected processor defaults as well as the ability to manage input/output 
operations for selected data sets. 



Authorized Program Facility (APF) 



There are six Access Method Services commands which require APF 
authorization; they are: 

• REPRO — when using the copy-catalog or catalog unload/reload facility. 

• PRINT — when the object to be printed is a VSAM catalog. 
. LISTCRA 

. EXPORTRA 
. RESETCAT 

• VERIFY — when a VSAM catalog is to be verified. 

If the problem program invoking Access Method Services needs to perform 
any of these functions, it must be authorized and be located in an authorized 
library. Additionally, a User I/O Routine must reside in an authorized library 
if the problem program it is associated with is authorized. See "Authorized 
Program Facility (APF)" in 0S/VS2 S)vtem Programming Library: 
Supervisor, for information about program authorization. 



Invoking Macro Instructions 



The following descriptions of the invoking macro instructions are related to 
Figure 30, which describes the argument lists referenced by the invoking 
macros. 



LINK or ATTACH Macro Instruction 



Access Method Services may be invoked through either the LINK or the 
ATTACH macro instruction. 

The format of the LINK or ATTACH macro instruction is: 

[ name ] 

{ LINK I ATTACH } 
EP=IDCAMS, 
PARAM=( optionaddr 
[ , dnameaddr ] 
[ , pgnoaddr ] 
[ , iolistaddr ] ), 
VL=1 

EP=IDCAMS 

specifies that the program to be invoked is IDCAMS. 
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specifies the addresses of the parameters to be passed to IDCAMS. These 
values can be coded: 



specifies the address of an option list, which can be specified in the 
PARM parameter of the EXEC statement and is a valid set of 
parameters for the Access Method Services PARM command. If you do 
not wish to specify any options, this address must point to a halfword of 
binary zeros. Figure 30 shows the format of the options list. 

dnameaddr 

specif ies the address of a list of alternate DD names for standard data 
sets used during IDCAMS processing. If standard DD names are used 
and this is not the last parameter in the list, it should point to a halfword 
of binary zeros. If it is the last parameter, it may be omitted. Figure 30 
shows the format of the alternate DD name list. 

pgnoaddr 

specifies the address of a 6-byte area which contains an EBCDIC 
starting page number for the system output fOe. If the page number is 
not specified, but this is not the last parameter in the list, the parameter 
must point to a halfword of binary zeros. If it is the last parameter, it 
may be omitted. If omitted the default page number is 1. Figure 30 
shows the format of the page-number area. 

ioHstaddr 

SpGdllCij tXlG tflOUrwtsO Ol o. Xlol' xjA. vA-tl^l Il<aliy ""^vOfcl ClllvO ClopLci iji&ifSls dOO lot? 

addresses of corresponding I/O routines. If no external I/O routines are 
supplied, this parameter may be omitted. Figure 30 shows the format of 

the I/O list. 

VL=1 

causes the high-order bit of the last address parameter of the PARAM 
Ust to be set to 1 . 



LOAD and CALL Macro Instructions 



Access Method Services may also be invoked via a LOAD of the module 
IDCAMS, followed by a CALL to that module. The format of the LOAD 
macro instruction is: 



[ name ] 


LOAD 


{EP=IDCAMS 1 EPLOC= address of name] 



where: 



EP=IDCAMS 

is the entry point name of the IDCAMS program to be loaded into 
virtual storage. 

EPLOC= address of name 

is the address of an 8-byte character string 'IDCAMS bb'. 
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After loading IDCAMS, Register 15 must be loaded with the address returned 
from the LOAD macro. Then CALL may be used to pass control to 
DDCAMS. The format of the CALL macro instruction is: 





LR 


15,0 


[ name ] 


CALL 


(15), 

( optionaddr 

[ , dnameaddr ] 

[ , pgnoaddr ] 

[ , iolistaddr ] ), 

VL 



\ 



where: 
15 



is the register containing the address of the entry point to be given 
control. 

optionaddr 

specifies the address of an options list which can be specified in the 
FARM parameter of the EXEC statement and is a valid set of 
parameters for the Access Method Services FARM command. If you do 
not wish to specify any options, this address must point to a halfword of 
binary zeros. Figure 30 shows the format of the options Ust. 

dnameaddr 

specifies the address of a list of alternate DD names for standard data 
sets used during IDCAMS processing. If standard DD names are used 
and this is not the last parameter in the list, it should point to a halfword 
of binary zeros. If it is the last parameter, it may be omitted. Figure 30 
shows the format of the alternate DD name Ust. 

pgnoaddr 

specifies the address of a 6-byte area which contains an EBCDIC 
starting page number for the system output file. If the page number is 
not specified, but this is not the last parameter in the list, the parameter 
must point to a halfword of binary zeros. If it is the last parameter, it 
may be omitted. If omitted the default page number is 1. Figure 30 
shows the format of the page number area. 

iolistaddr 

specifies the address of a hst of externally controlled data sets and the 
addresses of corresponding I/O routines. If no external I/O routines are 
supplied, this parameter may be omitted. Figure 30 shows the format of 
the I/O Ust. 



VL 



causes the high-order bit of the last address parameter in the macro 
expansion to.be set to L 
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Processor Condition Codes 



User I/O Routines 



The processor's condition code is LASTCC, which can be interrogated in the 
command stream following each functional command. The possible values, 
their meanings, and examples of causes are in the following table. The table 
illustrates the value of LASTCC. 

Code Meaning 

The function was executed successfully. Informational messages may have been 
issued. 

4 Some annoyance in executing the complete function was met, but it was possible to 
continue. The results may not be exactly what the user wants, but no permanent 
harm appears to have been done by continuing. A warning message was issued. 

8 A function could not perform all that was asked of it. The function was completed, 
but specific details were bypassed. 

12 The entire function could not be performed. 

16 Severe error or problem encountered. Remainder of command stream is flushed and 
processor returns condition code 16 to the operating system. 

LASTCC is set by the processor at the completion of each functional 
command. MAXCC, which can also be interrogated in the command stream, 
is the highest value of LASTCC thus far encountered. 



User I/O routines enable a user to perform all I/O operations for a data set 
which would normally be handled by the Access Methods Services processor. 
This makes it possible, for instance, to control the command input stream by 
providing an I/O routine for SYSIN. 

A user I/O routine is invoked by Access Method Services for all operations 
against the selected data sets. The identification of the data sets and their 
associated I/O routines is via the input/output list of the processor invocation 
parameter list (see Figure 30). 

When writing a user I/O routine, the user must be aware of three things: 
First, the processor handles the user data set as if it were a nonVSAM data 
set that contains variable-length unblocked records (maximum record length 
is 32760 bytes) with a physical sequential organization. The processor does 
not test for the existence of the data set. Second, the user must know the data 
format so that the user's routine can be coded to handle the correct type of 
input and format the correct type of output. Third, each user routine must 
handle errors encountered for data sets it is managing and provide a return 
code to the processor in register 15. The processor uses the return code to 
determine what it is to do next. 

The permissible return codes are: 

• — operation successful 

• A — end of data for a GET operation 

• 8— -error encountered during a GET/PUT operation, but continue 
processing 

• 12 — do not allow any further calls (except CLOSE) to this routine 
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OPTIONS LIST 



REG 1 ARGUMENT LIST 





PAGE NUMBER LIST 



LENGTH 



PAGE NUMBER 



/ 



PAGE NUMBER LIST: Optional. 
Provides a way to specify the starting 
page number for system output. 

LENGTH: The number of bytes in the 
PAGE NUMBER field. 

PAGE NUMBER: 1 4-byte character string 
which may specify the starting page number 
of system output listing. This value is reset to 
the current page number upon completion of 
the present invocation of the Access Method 
Services processor. 
INPUT/OUTPUT LIST 



f 



DNAME 



^1^ lOROUTINE, 



t 



USER DATAi 



f DNAMEfi 



lOROUTINEr 



^USER DATA, 



OPTIONS LIST: Required. Provides a 
way to specify processing options. If 
you do not wish to specify any options, 
you must set the LENGTH field to 
binary zeros. 

LENGTH: Halfword which specifies the 
number of bytes in the OPTIONS field. 

OPTIONS: Character string which contains 
the processing options'of the Access Method 
Services PARM command. The options may 
be specified in the PARM field of the EXEC 
statement or they may be set up by the prob 
problem program. The options must comply 
to the parameter syntax of the Access Method 
Services PARM command. 



DNAME LIST 



LENGTH 



00000000 



INPUT/OUTPUT LIST: OptionaL Provides the means 
of identifying those data sets for which the invoker 
wishes to manage all I/O operations. 

n: A fuUword which specifies the number of groups of 
three fields that follows. Each group consists of a 
DNAME address, and lOROUTINE address and a USER 
DATA address. 

DNAME: Address of a character string which identifies 
a data set which will result in the invocation of the 
associated lOROUTINE for all I/O operations (including 
OPEN and CLOSE) against the data set. The character 
string identifies the data set as either a 10-byte or 46- 
byte character string as follows: 

A 10-byte character string: the first two characters 
are 'DD', the next 8 characters are the DNAME field 
value left-justified (padded with blanks if necessary) 
which may appear in the FILE, IN FILE, or OUTFILE 
parameter of any Access Method Services .command. 
The SYSIN and SYSPRINT ddnames may also appear 
if the invoker wishes to manage these data sets. 



A 46-byte character string: the first two characters are 
'DS' the next 44 characters are the data set name, left- 
justified (padded with blanks if necessary), which may 
appear in the INDATASET, OUTDATASET, or DATASET 
parameters of any Access Method Services command. 



00000000 



00000000 



00000000 



SYSiNbbb 



SYSPRINT 



DNAMES LIST: Optional. 
Provides a way to specify 
alternative names for the 
SYSIN and SYSPRINT 
data sets. 

LENGTH: Halfword which 
specifies the number of 
bytes in the remainder 
of the list. 

DNAMES: Unseparated 
eight-character DDnames 
left jsutified and padded 
with blanks. To change 
the name of SYSIN or 
SYSPRINT, supply an 
alternate name in the 
same position. If an 
alternate name is not 
supplied, the standard 
name is assumed. If the 
name is not supplied 
with the list, the eight- 
byte entry must contain 
binary zeros. Names in 
any position other than 
those for SYSIN and 
SYSPRINT are ignored. 



lOROUTINE: Address of the program which is to be 
invoked to process I/O operations upon the data set 
associated with DNAME. This routine, instead of the 
processor, will be invoked for all operations againist 
the data set. See the section "User I/O Routines" in 
this appendix for linkage and interface conventions 
between the lOROUTINE and Access Method Services. 

USER DATA: Address of a data area user may use for any purpose. 
Figure 30. Processor Invocation Argument List From a Problem Program 
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t 



USER DATA 



I lOFLAGS 




I lOINFO 



User data pointer obtained from the 
input/output list of the processor 
invocation parameter list. (See Figure 30.) 



OPEN 



DNAME or 
DATASETNAME 



DNAME: 8-byte field, left-justified 
(padded with blanks if necessary) 
containing the DDname. 

DATASETNAME: 44-bytc field 
(padded with blanks if necessary) 
containing the data set name. 

CLOSE 



For a GET, this information 
is returned to the processor 
by the user's I/O routine in 
the 8-byte area passed to the 
routine. 

For a PUT, the processor gives 
this information to the user's 
I/O routine. 

Record (GET): Address of 
retrieved record. 

Record Length (GET): Full- 
word length of retrieved 
record. 

Record (PUT): Address of 
record to be written. 

Record Length (PUT): Full- 
word length of record to be 
written. 




FLAGS 



Fullword of I'lags: 



DATASETNAME: 44-byte 
field (padded with blanks 
if necessary) containing 
the data set name. 





Value or 
Bit Pattern 


Meaning 


Byte 1 
(Operation) 


X'OO' 
X'04' 
X'08' 
X'OC 


OPEN - 
CLOSE 
GET 
PUT 


Byte 2 


1 

,1 

..I ..... 


OPEN for input 
OPEN for output 
Indicates lOINFO 
contains the address 
of a DDname on OPEN. 



... 1 



Bytes 3, 4 
(Record type 
for PUT only) 



Indicates lOINFO contains 
the address of a data set 
name on OPEN. 

Normal data record is to 
be written. 



Message serial number 
converted to binary if 
IDC message is to be 
written. (See "User I/O 
Routine" for a description 
of this value.) 



Figure 3 1 . Arguments Passed to and From a User I/O Routine 
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Figure 3 1 shows the argument list used in communication between the user 
I/O routine and the Access Method Services processor. The User I/O routine 
is invoked by the processor for OPEN, CLOSE, GET, and PUT routines. 

The type of operation to be performed is indicated via the lOFLAGS. The 
lOINFO field indicates, for OPEN and CLOSE operations, the data set name 
or ddname of the data set; for GET and PUT operations, the lOINFO field is 
used to communicate the record length and address. 

A user I/O routine for SYSPRINT receives control each time the processor 
issues a PUT against the SYSPRINT data set. If the PUT has been issued to 
print an IDC message, the unique message number is passed to the routine via 
JOFLAGS (see Figure 31). Each IDC message is in the form IDCsnnnl or 
IDCsnnnnl, where: 

5 is a code indicating the severity of the problem 

nnn or nnnn is the message number which is unique across all IDC 
messages 

The 2-byte message number passed via lOFLAGS is the nnn or nnnn portion 
of the message converted to binary. 
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12. RelPL the system (a cold start). The systemtshould now be usmg the new 
VSAM master catalog, the redefined storage index, and the newly defined 
page data sets. 

13. Clean up the scratch pack using the ALTER command with the 
REMOVEVOLUMES parameter. 

14. Recatalog all the remaining nonVSAM data sets into the new master 
catalog. 

15. Connect (and define aliases for) OS catalogs (CVOLs) that were 
connected to the old master catalog. 

16. Redefine the data spaces that were deleted from the old master catalog. 

17. Import the previously exported VSAM data sets into the new master 
catalog. 

18. Import (with the CONNECT parameter) and define aliases for user 
catalogs that were connected to the old master catalog. 

Your new master catalog is now reestablished. In this example, the new 
master catalog is recoverable (that is, its volume includes a catalog recovery 
area and can be processed with the LISTCRA, EXPORTRA, IMPORTRA, 
and RESETCAT commands). 

Figure 32 shows an example of the job stream needed to make your master 
catalog a recoverable catalog. The step numbers in the jobs correspond to the 
steps described previously. 

If your old master catalog is already recoverable, you can use the 
EXPORTRA and IMPORTRA commands rather than the EXPORT and 
IMPORT commands as used in this example. You can use EXPORTRA for 
ail volumes owned by the master catalog, including the master catalog 
volume, in place of step 2 above. After redefining any VSAM data spaces 
(step 16), you can use IMPORTRA in place of steps 14, 15, 17, and 18. 
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APPENDIX H: CHANGING THE ATTRIBUTES OF 
THE VSAM MASTER CATALOG 



At some point in time in an existing OS/VS2 MVS system, you may wish to 
change some of the attributes of your VSAM master catalog. For example, 
you may wish to convert the VSAM master catalog from nonrecoverable to 
recoverable, or take advantage of a new VSAM enhancement. This is an 
example of the conversion process. A description of the process precedes an 
actual example of each step. When you understand the example's objectives, 
you can modify it so that it is appropriate for your system. 

1. Install on your system the level (or higher level) of VSAM and Access 
Method Services that supports the features you desire. 

2. Export (with the PERMANENT attribute) all VSAM data sets from the 
old master catalog. Ignore for the moment the storage index and page 
data sets in the old master catalog. 

3. Mount a scratch pack to hold a temporary catalog, a storage index, and 
the page data sets. 

4. Define a temporary master catalog on the scratch pack. You can specify 
either DEFINE MASTERCATALOG or DEFINE USERCATALOG. In 
either case, VSAM creates a user catalog which can then be referenced in 
step 6 and used for the EPL in step 7. 

5. Catalog the nonVSAM data sets needed for an IPL on the temporary 
master catalog. Define a new storage index and page data sets on the 
scratch volume in the temporary catalog. The page data sets should have 
the same name as the original page data sets so that the lEASYSCK) 
member in SYSl.PARMLIB need not be replaced. 

6. Alter the SYSCATLG member of the SYS 1 .NUCLEUS data set so that it 
points to the temporary catalog. 

7. IPL the system (cold start procedure). The system now is using the 
temporary catalog as the master catalog, and refers to the storage index 
data set and page data sets cataloged in the temporary catalog. 

8. Use the ALTER REMOVEVOLUMES command to remove VSAM 
from the volumes containing the old master catalog, the old page data 
sets, and the old storage index, and to remove VSAM from any volumes 
owned by the old master catalog. 

9. Define the new catalog in place of the original. This catalog will 
eventually become the VSAM master catalog. As in step 4, you can 
specify either DEFINE MASTERCATALOG or DEFINE 
USERCATALOG. 

10. Redefine the storage index and page data sets in their original locations 
on the new master catalog. (Allow room for the catalog recovery area if 
the new catalog has been defined with the recoverable attribute.) Catalog 
all nonVSAM data sets needed for IPL in the new master catalog. 

IL Replace the SYSCATLG member in SYS 1. NUCLEUS (now cataloged in 
the new master catalog) so that the SYSCATLG member points to the 
new master catalog. 
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DEFINE PAGESPACE - 

(NAME(SP00L1P1 ) - 

FILE(CATPAK) - 

CYLINDERS (80) - 

VOLUMECCATPAK) - 

UNIQUE ) - 

CATALOG! TEMPCAT ) 
DEFINE PAGESPACE - 

(NAME{SP00L1P2) - 

FILE(CATPAK) - 

CYLINDERS (40) - 

VOLUME( CATP'AK ) - 

UNIQUE ) - 

CATALOG ( TEMPCAT ) 

/* 

//STEP6A EXEC PGM=IEHPROGM,COND=( , LT ) 

//SG2001 DD DISP=OLD,VOL=SER=SG2001 ,UNIT=3330 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

SCRATCH DSNAME=SYS1 .NUCLEUS, VOL=3330=SG2001 , MEMBER=SYSCATLG 

/* 

//STEP6B EXEC PGM=IEBGENER,COND=( ,LT ) 

//SYSIN DD DUMMY 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSN=SYS1 .NUCLEUS( SYSCATLG ) ,DISP=( OLD, KEEP ) , 

// DCB=BLKSIZE=13030,VOL=SER=SG2001 ,UNIT=3330 

//SYSUT1 DD * 

CAPAK ( See Note 1 ) 

/* 

//* STEP 7 - IPL THE SYSTEM 

// 

//J0B2 JOB ... 

//STEPS EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//DD3330 DD UNIT=3330,DISP=OLD, VOL=SER=( SG2001 , SP00L1 ) 

//SYSIN DD * 

ALTER TEMPCAT RVOL ( SG2001 SPOOL 1 ) FILE ( DD3330 ) 

/* 

//STEP9 EXEC PGM=IDCAMS,COND=(0,LT) 
//SYSPRINT DD SYSOUT=A 

//SG2001 DD UNIT=3330,VOL=SER=SG2001 ,DISP=OLD 
//SYSIN DD * 

Figure 32 (Part 2 of 4). Sample Job Stream to Make the Master Catalog Recoverable 
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INSTALL VSAM ON YOUR SYSTEM 

PGM=IDCAMS 

SYSOUT=A 
statements that describe the output data sets 

* 

commands required to export the VSAM data sets and user 
connector entries from the old master catalog 



//J0B1 JOB . . 
//* STEP 1 - 
//STEP2 EXEC 
//SYSPRINT DD 
//* DD 
//SYSIN DD 

EXPORT 

catalog 
/* 

//* STEP 3 - MOUNT A SCRATCH PACK 

//STEP4 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//CATPAK DD UNIT=3330,VOL=SER=CATPAK,DISP=OLD 

//SYSIN DD * 

DEFINE MASTERCATALOG - 

( NAME( TEMPCAT ) - 

FILE( CATPAK) - 

VOLUME (CATPAK) - 

CYLINDERS (12 1 ) ) 

/* 

//STEPS EXEC PGM=IDCAMS , COND=( , LT ) 

//STEPCAT DD DSN=TEMPCAT,DISP=OLD 

//SYSPRINT DD SYSOUT=A 

//CATPAK DD UNIT=3330,VOL=SER=CATPAK,DISP=OLD 

//SYSIN DD 



NAME(SYS1 .LPALIB ) VOL(SG2001) DEV( 3330 ) ) 
NAME(SYS1 .LINKLIB ) VOL(SG2001) DEVT( 3330 ) ) 
NAME(SYS1 .DSSVM ) VOL(SG2001) DEVT( 3330 ) ) 



NAME(SYS1 .SVCLIB ) 
NAME ( SYS 1 .NUCLEUS 



NAME(SYS1.DCMLIB 
NAME ( SYS 1 .INDMAC 
NAME ( SYS 1 .CMDLIB 
NAME ( SYS 1 .CMDLIB 
NAME( SYS 1 .HELP ) 
NAME ( SYS 1 .SAMPLIB 



DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT( TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 

DEF CAT (TEMPCAT) NVSAM 
DEF CLUSTER - 

( NAME ( SYS 1 . STGINDEX ) 

FILE (CATPAK) 

KEYS(12,8) - 

CYLINDERS (6,0) - 
- RECORDSIZE( 2041 ,2041 ) - ' 

VOLUME (CATPAK) - 

UNIQUE ) - 

DATA( CONTROLINTERVALSIZE( 2048 ) ) - 

CATALOG ( TEMPCAT ) 

Figure 32 (Part 1 of 4). Sample Job Stream to Make the Master Catalog Recoverable 



VOL(SG2001 ) 

VOL(SG2001 ) 
VOL(SG2001 ) 
VOL(SG2001 ) 
VOL(SG2001 ) 
VOL(SG2001 ) 
VOL(SG2001) DEVT(3330)) 
)VOL(SG2001) DEVT(3330)) 



DEVT(3330) ) 

DEVT( 3330 ) ) 
DEVT( 3330 ) ) 
DEVT( 3330 ) ) 
DEVT( 3330 ) ) 
DEVT(3330) ) 



NAME(SYS1 .MACLIB )VOL(SG2001) DEVT( 3330 ) ) 
NAME(SYS1 .PROCLIB )VOL(SG2001) DEVT( 3330 ) ) 
NAME(SYS1 .TELCMLIB ) VOL(SG2001 ) DEVT( 3330 ) ) 
NAME(SYS1 .UADS ) VOL(SG2001) DEVT( 3330 ) ) 
NAME(SYS1 .VTAMLIB )VOL(SG2001) DEVT( 3330 ) ) 
NAME(SYS1 .IMAGELIB )VOL(SG2001) DEVT( 3330 ) ) 
PARMLIB ) VOL(SG2001) DEVT( 3330 ) ) 
BRODCAST ) VOL(SG2001) DEVT( 3330 ) ) 



NAME ( SYS 1 
NAME ( SYS 1 
NAME ( SYS 1 
NAME ( SYS 1 
NAME ( SYS 1 
NAME(SYS1 
NAME ( SYS 1 



MANX ) 
MANY ) 
DUMP 00 
DUMP 01 
LOGREC 



VOL(SG2001) DEVT(3330)) 
VOL(SG2001) DEVT(3330)) 
)VOL(SG2001) DEVT(3330)) 



VOL(SG2001 ) 
VOL(SG2001 ) 



DEVT(3330) ) 
DEVT( 3330) ) 



n 
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(that is, the user's program processes a control interval, 
rather than a data record, as a logical entity). 

control-interval ^Ht: The movement of some of the stored 
records in a control interval to a free control interval, to 
make possible the insertion or lengthening of a record that 
won't fit in the original control interval. 

CRA: Catalog recovery area. An entry-sequenced data set 
that exists on each volume owned by a recoverable catalog, 
including the volume on which the catalog resides. The CRA 
contains copies of the catalog's records, and can be used to 
recover a damaged catalog. 

data component: That part of a VSAM data set, alternate , 
index, or catalog that contains the object's data records. 

data entry: A catalog entry that describes the data component 
of a cluster, alternate index, page spaces, or catalog. A data 
entry contains the data component's attributes, allocation and 
extent information, and statistics. A data entry for a cluster's 
or catalog's data component can also contain the data 
component's passwords and protection attributes. 

data integrity: Preservation of data or programs for their 
intended purpose. As used in this publication, the safety of 
data from inadvertent destruction or alteration. 

data record: A collection of items of information from the 
standpoint of its use in an application, as a user supplies it to 
VSAM for storage. 

data security: Prevention of access to or use of data or 
programs without authorization. As used in this publication, 
the safety of data from unauthorized use, theft, or purposeful 
destruction. 

data set: The major unit of data storage and retrieval in the 
operating system, consisting of data in a prescribed 
arrangement and described by control information to which 
the system has access. As used in this publication, a collection 
of fixed- or variable-length records in auxiliary storage, 
arranged by VSAM in key sequence or in entry 
sequence. (See abo key-sequenced data set and 
entry-sequenced data set.) 

data space: A storage area defined in the volume table of 
contents of a direct-access volume for the exclusive use of 
VSAM to store data sets, indexes, and catalogs. 

desiage: (verb) To transmit data from a direct-access storage 
staging drive to a mass-storage volume. 

direct access: The retrieval or storage of data by a reference to 
its location in a data set rather than relative to the previously 
retrieved or stored data. {See also addressed direct access and 
keyed direct access.) 

distributed free space: Space reserved within the control 
intervals of a key-sequenced data set for inserting new 
records into the data set in key sequence; also, whole control 
intervals reserved in a control area for the same purpose. 

dynamic allocation: The allocation of a data set or volume by 
the use of the data set name or volume serial number rather 
than by the use of information contained in a JCL statement. 

entry: A collection of information about a cataloged object in 
a VSAM master or user catalog. Each entry resides in one or 
more 512-byte record. 

entry name: A unique name for each component or object as it 
is identified in a catalog. The entryname is the same as the 
dsname in a DD statement that describes the object. 



entry sequence: The order in which data records are physically 
arranged (according to ascending RB A) in auxiliary storage, 
without respect to their contents. {Contrast to key sequence.) 

entiy-sequenced data set: A data set whose records are loaded 
without respect to their contents, and whose RBAs cannot 
change. Records are retrieved and stored by addressed access, 
and new records are added at the end of the data set. 

exception: An abnormal condition such as an I/O error 
encountered in processing a data set. 

exception exit: A user-written exit routine that attempts to 
recover from exceptional processing situations and is 
processed before the SYNAD exit routine gets control. The 
exception-exit routine is similar to the SYNAD error exit 
routine, except that the exception-exit routine can be tailored 
by the user for the data or index component of a VSAM data 
set or alternate index. 

extent: A continuous space allocated on a direct-access 
storage volume, reserved for a particular data space or data 
set. An extent of a data set contains a whole number of 
control areas. 

external sort: Sorting of data records into a new sequence 
using a small amount of virtual storage and two temporary 
sortfiles (entry-sequenced data sets) on a direct-access storage 
volume. {See also internal sort.) 

field: In a record or a control block, a specified area used for 
a particular category of data or control information. 

free space: {See distributed free space.) 

generation data group entry: An entry that permits nonVSAM 
data sets to be associated with other nonVSAM data sets as 
generation data sets. 

generation data set: One of a collection of historically related 
nonVSAM data sets; the collection of these data sets is known 
as a generation data group. 

generic key: A high-order portion of a key, containing 
characters that identify those records that are significant for a 
certain application. For example, it might be desirable to 
retrieve all records whose keys begin with the generic key AB, 
regardless of the full key values. 

generic name: A qualified name in which one qualifier is 
replaced by an asterisk; the generic name applies to all entries 
that match the qualifiers supplied in the generic name. 

horizontal pointer: A pointer in an index record that gives the 
location of another index record in the same level that 
contains the next key in collating sequence; used for keyed 
sequential access. 

index: As used in this publication, an ordered collection of 
pairs, each consisting of a key and a pointer, used by VSAM 
to sequence and locate the records of a key-sequenced data 
set; organized in levels of index records. {See also index level, 
index set, and sequence set.) 

index component: That part of a key-sequenced data set, 
catalog, or alternate index, that establishes the sequence of 
the data records within the object it indexes. The index is 
used to locate each record in the object's data component, 
based on the record's key value. 

index entry: A catalog entry that describes the index 
component of a key-sequenced cluster, alternate index, or 
catalog. An index entry contains the index component's 
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DEFINE MASTERCATALOG - 
(NAME(AMASTCAT) - 
FILE(SG2001) - 
VOLUME (SG2001 ) - 
CYLINDERS ( 12 1) - 
RECOVERABLE ) 

/* 

//STEPIO EXEC PGM=IDCAMS,COND=(0,LT) 

//STEPCAT DD DSN=AMASTCAT,DISP=OLD 

//SYSPRINT DD SYSOUT=A 

//SP00L1 DD UNIT=3330,VOL=SER=SPOOL1 ,DISP=OLD 

//SG2001 DD UNIT=3330,VOL=SER=SG2001 ,DISP=OLD 

//SYSIN DD * 

DEF CLUSTER - 

( NAME ( S YS 1 . STGINDEX ) - 

FILE (SG2001 ) - 

KEYS(12,8) - 

CYLINDERS (6,0) - 

RECORDSIZE( 2041 ,2041 ) - 

VOLUME(SG2001 ) - 

UNIQUE ) - 

DATA( CONTROLINTERVALSIZE ( 2048 ) ) - 

CATALOG ( AMASTCAT ) 
DEFINE PAGESPACE - 

(NAME(SP00L1P1 ) - 

FILE( SP00L1 ) - 

CYLINDERS ( 140) - 

VOLUME ( SPOOL 1 ) - 

UNIQUE ) - 

CATALOG ( AMASTCAT ) 
DEFINE PAGESPACE - 

(NAME( SPOOL 1P2) - 

FILEC SP00L1 ) - 

CYLINDERS ( 40 ) - 

VOLUME ( SPOOL 1 ) - 

UNIQUE ) - 

CATALOG! AMASTCAT ) 



DEF CAT (AMASTCAT 
DEF CAT( AMASTCAT 
DEF CAT (AMASTCAT 
DEF CAT( AMASTCAT 
DEF CAT( AMASTCAT 
DEF CAT( AMASTCAT 
DEF CAT (AMASTCAT 
DEF CAT( AMASTCAT 
DEF CAT (AMASTCAT 
DEF CAT( AMASTCAT 
DEF CAT( AMASTCAT 
DEF CAT( AMASTCAT 
DEF CAT (AMASTCAT 
DEF CAT( AMASTCAT 
DEF CAT (AMASTCAT 



NVSAM ( NAME( SYS1 .LPALIB ) VOL( SG2001 ) DEVT( 3330 ) ) 
NVSAM ( NAME ( SYS 1 .LINKLIB ) VOL(SG2001) DEVT( 3330 ) ) 
NVSAM ( NAME ( SYS 1 .DSSVM ) VOL(SG2001) DEVT( 3330 ) ) 
NVSAM ( NAME ( SYS 1 .SVCLIB ) VOL(SG2001) DEVT( 3330 ) ) 
NVSAM ( NAME (SYS1. NUCLEUS ) VOL(SG2001) DEVT(3330)) 
NVSAM ( NAME ( SYS 1 .DCMLIB ) VOL(SG2001) DEVT( 3330 ) ) 
NVSAM ( NAME( SYS1 . INDMAC ) VOL( SG2001 ) DEVT( 3330 ) ) 
NVSAM (NAME(SYS1.CMDLIB ) VOL(SG2001) DEVT( 3330 ) ) 
NVSAM ( NAME ( SYS 1 .HELP ) VOL(SG2001) DEVT( 3330 ) ) 
NVSAM ( NAME ( SYS 1 .SAMPLIB ) VOL(SG2001) DEVT( 3330 ) ) 
NVSAM ( NAME ( SYS 1.MACLIB ) VOL(SG2001) DEVT( 3330 ) ) 
NVSAM ( NAME ( SYS 1 .PROCLIB ) VOL(SG2001) DEVT( 3330 ) ) 
NVSAM ( NAME ( SYS 1 .TELCMLIB ) VOL(SG2001) DEVT( 3330 ) 
NVSAM ( NAME ( SYS 1 .UADS ) VOL(SG2001) DEVT( 3330 ) ) 
NVSAM ( NAME ( SYS 1 .VTAMLIB ) VOL(SG2001) DEVT( 3330 ) ) 



Figure 32 (Part 3 of 4). Sample Job Stream to Make the Master Catalog Recoverable 
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qualified name: A name that is segmented by periods; each 
name segment is referred to as a qualifier. 

random access: {See direct access.) 

RBA: Relative byte address. The displacement of a data 
record or a control interval from the beginning of the data set 
to which it belongs; independent of the manner in which the 
data set is stored. 

record: (See index record, data record, stored record.) 

record replacement: An enhancement of the REPRO 
command which allows the user to merge two data sets and, 
when duplicate records are found (that is, the key values of 
two records are equal) the data record from the source data 
set replaces the data record in the target data set. 

recoverable catalog: A catalog defined with the recoverable 
attribute. Duplicate catalog entries are put into CRAs that 
can be used to recover data in the event of catalog failure. 
(See also CRA.) 

recovery volume: The first volume of a prime index, if the 
VSAM data set is key-sequenced cluster; otherwise, the first 
volume of the data set, if ESDS. 

relative byte address: {See RBA.) 

relative record: A data record whose position depends on its 
placement within a a group of data records; its position, or 
record number, is its displacement, in records, from the 
beginning of the data set. 

relative-record data set: A data set whose records are loaded 
into fixed-length slots. 

relative-record number: A number that identifies not only the 
slot, or record space, in a relative-record data set but also the 
record occupying the slot. 

replication: {See index replication.) 

reusable data set: A VSAM data set that can be used as a 
workfile regardless of its old contents. 

secondary space aOocation: A contiguous space on a 
direct-access device, occupied by or reserved for a particular 
data set, which is allocated after space in the primary extent 
has been exhausted. {See also primary space allocation.) 

security: {See data security.) 

sequence checking: The process of verifying the order of a set 
of records relative to some field's collating sequence. 

sequence set: The lowest level of the index of a key-sequenced 
data set; it gives the locations of the control intervals in the 
data set and orders them by the key sequence of the data 
records they contain. The sequence set and the index set 
together comprise the index. 

sequential access: The retrieval or storage of a data record in 
either its entry sequence or its key sequence, relative to the 
previously retrieved or stored record. {See also addressed 
sequential access and keyed sequential access.) 

simple name: A qualifier of a qualified entryname or dsname. 
Simple names may be one to eight characters and, in a series, 
are separated from each other by a period. 

skip sequential access: Keyed sequential retrieval or storage of 
records here and there throughout a data set, skipping 
automatically to the desired record or collating position for 
insertion: VSAM scans the sequence set to find a record or a 
collating position. 



slot: The space for a data record in a relative-record data set. 

sort: {See external sort, internal sort, and collating sequence.) 

spanned record: A logical record whose length exceeds control 
interval length, and crosses (or spans) one or more control 
interval boundaries within a control area. 

stage: (verb) To transmit data from a mass-storage volume to 
a direct-access storage staging drive. 

step catalog: {See job catalog.) 

stored record: A data record, together with its control 
information, as stored in auxiliary storage. 

upgrade set: AH the alternate indexes that VSAM has been 
instructed to update whenever there is a change to the data 
component of the base cluster. 

user catalog: A catalog used in the same way as the master 
catalog, but optional and pointed to by the master catalog, 
and also used to lessen the contention for the master catalog 
and to facilitate volume portability. 

user catalog connector: {See catalog connector.) 

vertical pointer: A pointer in an index record of a given level 
that gives the location of an index record in the next lower 
level or the location of a control interval in the data set 
controlled by the index. 

volume cleanup: The process of deleting all VSAM data spaces 
from a volume and removing a VSAM catalog's ownership of 
the volume, even though the volume contains VSAM data 
records. 

volume entry: A catalog entry that describes a volume owned 
by the catalog. All VSAM data spaces on the volume are 
described in the volume entry and the catalog is no longer 
available. 
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GLOSSARY 






The following terms are defined as they are used in this book. 
If you do not find the term you are looking for, refer to the 
index or to the Data Processing Glossary, GC20-1699. 

Access Method Services: A multifunction service program that 
defines VSAM data sets and allocates space for them, 
converts indexed-sequential data sets to key-sequenced data 
sets with indexes, modifies data-set attributes in the catalog, 
reorganizes data sets, facilitates data portability between 
operating systems, creates backup copies of data sets and 
indexes, helps make inaccessible data sets accessible, and lists 
the records of data sets and catalogs. 

addressed direct access: The retrieval or storage of a data 
record identified by its RBA, independent of the record's 
location relative to the previously retrieved or stored record. 
(See also keyed direct access, addressed sequential access, 
and keyed sequential access.) 

addressed sequential address: The retrieval or storage of a data 
record in its entry sequence relative to the previously 
retrieved or stored record. (See also keyed sequential access, 
addressed direct access, and keyed direct access.) 

alias: An alternative name for an entry. 

alias entry: An entry that relates an alias (alternate 
entryname) to the real entryname of a user catalog or 
nonVSAM data set. 

alternate index: An ordered collection of records, each 
consisting of a key (called the alternate key) and one or more 
pointers. An alternate index is used by VSAM to sequence 
and locate the records of a key-sequenced or entry-sequenced 
VSAM data set. An alternate index is organized as a 
key-sequenced data set. (See also alternate key, base cluster, 
and path.) 

altemate-index entry: A catalog entry that contains 
information about an alternate index. An alternate index is 
conceptually a key-sequenced cluster, and is cataloged in the 
same way. An alternate-index entry points to a data entry and 
an index entry to describe the alternate-index's components, 
and to a cluster entry to identify the alternate-index's base 
cluster. (See also cluster entry.) 

ahemate-index record: A collection of items used to sequence 
and locate one or more data records in a base cluster. Each 
alternate-index record contains an alternate-key value and 
one or more pointers. When the alternate index supports a 
key-sequenced data set, each data record's prime key value is 
the pointer. When the alternate index supports an 
entry-sequenced data set, the data record's RBA value is the 
pointer. (See also alternate index, alternate key, base cluster, 
and key.) 

alternate key: One or more characters within a data record, 
used to identify the data record or control its use. Unlike the 
prime key, the alternate key can identify more than one data 
record. (See also key and key field.) 

application: As used in this publication, the use to which an 
access method is put or the end result that it serves; 
contrasted to the internal opjeration of the access method. 

backup data set: A copy that can be used to replace or 
reconstruct a damaged data set. 



base cluster: The VSAM cluster whose data records are to be 
accessed through a path. Usually, a base cluster is the 
key-sequenced or entry-sequenced data set which an alternate 
index supports (that is, an alternate index is used by VSAM to 
sequence and locate the data records of a base cluster). (See 
also alternate index and path.) 

bind: (verb) To keep a data set that has been staged from a 
mass-storage volume to a direct-access storage staging drive 
on the staging drive until the data set is closed. 

catalog: (See master catalog and user catalog.) 

catalog cleanup: A process that allows you to delete entries if 
their volume is no longer available; catalog cleanup also 
allows you to delete a catalog even though it is not empty. 
Catalog cleanup is a function of the DELETE command. 

catalog connector: A catalog entry, called either a user catalog 
entry or a catalog connector entry, in the master catalog that 
points to a user catalog's volume (that is, it contains the 
volume serial number of the direct-access volume that 
contains the user catalog). 

catalog recovery area: (See CRA.) 

duster: A data component and an index component when 
data is key sequenced; a data component alone when data is 
entry sequenced. 

cluster entry: A catalog entry that contains information about 
a key-sequenced or entry-sequenced VSAM cluster: 
ownership, cluster attributes, and the cluster's passwords and 
protection attributes. A key-sequenced cluster entry points to 
a data entry and an index entry. An entry-sequenced cluster 
entry points to a data entry. 

coDatii^ sequence: An ordering assigned to a set of items, such 
that any two sets in that assigned order can be collated. As 
used in this publication, the order defined by the System/370 
8-bit code for alphabetic, numeric, and special characters. 

component: The data portion or, for a key-sequenced cluster, 
alternate index, or VSAM catalog, the index portion or a 
VSAM object. In this book, the components of an object are 
usually referred to as the object's data component and index 
component. 

compressHon: (See key compression.) 

control area: A group of control intervals used as a unit for 
formatting a data set before adding records to it. Also, in a 
key-sequenced data set, the set of control intervals pointed to 
by a sequence-set index record; used by VSAM for 
distributing free space and for placing a sequence-set index 
record adjacent to its data. 

control-area split: The movement of the contents of some of 
the control intervals in a control area to a newly created 
control area, to make possible the insertion or lengthening of 
a data record when a free control interval was needed and 
there was none in the original control area. 

control interval: A fixed-length area of auxiliary-storage space 
in which VSAM stores records and distributes free space. It is 
the unit of information transmitted to or from auxiliary 
storage by VSAM. 

control interval access: The retrieval and storage of a VSAM 
data-set's contents, based on the RBA of a control interval 
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BLDINDEX command 95,169 
catalog parameter 170 

DD statements that describe the SORT workfiles 97 
example 172 
format 169 

how an alternate index is built 95 
order of catalog use 97 
parameters 169 

Optional parameters 170 
Required parameters 169 
sort parameters 97 
bold face type, in notation conventions 6 
braces, in notation conventions 6 
brackets, in notation conventions 6 
BUFFERSPACE parameter 
in ALTER command 155 
in DEFINE command 

used to define an alternate index 196 
used to define a catalog 301 
used to define a cluster 229 
building an alternate index 95,169 

c 

calculating space for a catalog 77 

CALL macro, invoking Access Method Services with 40,529 

CANDIDATE parameter (DEFINE SPACE) 292 

capitalization, in notation conventions 6 

catalog 

(see also master catalog and user catalog) 

allocating user catalogs 77 

altering 99,151 

backing up 61,141 

calculating space for 80 

cleanup 65 

connecting to master catalog (IMPORT) 1 1 1 ,347 

converting devices 135 

creating 297 

defining 77 

displaying 103 

dumping a 61 

duplicate names, preventing 72 

entries, moving 1 1 1 

identifying the volume of a 80 

listing 103 

master 45 

modifying 99 

order of use 
ALTER 100 
BLDINDEX 97 
DEFINE 73 
DELETE 108 
LISTCAT 103 

OS CVOLs (control volumes) 48 

OS entries, converted to VS AM entries 49, 1 1 5 

ownership of a volume 42,63 

preventing duplicate names 72 

protecting 60 

recovery 66,123 

relationships among 46 

reloading 142 

resetting catalog entries 129 

restoring the entries after system failure 62,123 

secondary allocation amount 82 

setting up the master catalog 45 

space estimates 80 



space, allocation of 77 

transporting user catalogs 65 

unloading 142 

update password and nonVSAM data sets 80 

use of, with data and space management 44 

user catalog defined on a mass storage volume 77 

using a backup copy 61 

using a model to define 303 

using qualified names for cataloged objects 44 

VSAM'suseof 44 
catalog entries in OS catalog converted 48, 1 1 5 

entry types and VSAM equivalents 117 
CATALOG parameter 

in ALTER command 1 56 

in BLDINDEX command 170 

in CNVTC AT command 177 

in DEFINE command 
ALIAS 181 

ALTERNATEINDEX 214 
Catalog 307 
CLUSTER 247 

GENERATIONDATAGROUP 261 
NONVSAM 267 
PAGESPACE 278 
PATH 288 
SPACE 293 
USERCATALOG 307 

in DELETE command 3 1 7 

in IMPORT command 350 

in IMPORTRA command 362 

in LISTCAT command 372 

in LISTCRA command 377 

in RESETCAT command 405 
catalog password protection 53 
catalog record 

deleting 105 

listing 103 

modifying 99 

resetting 129 

restoring after system failure 123 
catalog recovery 66 
catalog recovery area 66,123 

contents, description of 123 

copying an entry from 125 

listing the 125 

examples of output 496 

procedure for using 123 

space allocation 83 
catalog use, order of, with 

ALTER 100 

BLDINDEX 97 

DEFINE 73 

DELETE 108 

LISTCAT 103 
cataloging 

aliases 91,181 

alternate indexes 88 

clusters 85 

data sets 81,91 

entry-sequenced data sets 8 1 

general discussion of 71 

key-sequenced data sets 81 

nonVSAM data sets 91 

user catalogs 44 
CHAIN parameter (FARM) 419 

of master catalog 535 
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attributes, passwords and protection attributes, allocation 
and extent information, and statistics. 

V index level: A set of index records that order and give the 

^ location of records in the next lower level or of control 

^ intervals in the data set that it controls. 

index record: A collection of index entries that are retrieved 
and stored as a group. (Contrast to data record.) 

index replication: The use of an entire track of direct-access 
storage to contain as many copies of a single index record as 
possible; reduces rotational delay. 

index set: The set of index levels above the sequence set. The 
index set and the sequence set together comprise the index. 

index upgrade: The process of updating an alternate index to 
reflect the changes made to the contents of its base cluster. 

integrity: (See data integrity.) 

internal sort: Sorting of data records into a new sequence 
using virtual storage and no temporary data sets on a 
direct-access storage device. (See also external sort.) 

ISAM interface: A set of routines that allow a processing 
program coded to use ISAM (indexed sequential access 
method) to gain access to a key-sequenced data set with an 
index. 

job catalog: A catalog made available for a job, by means of a 
JOBCAT DD statement, or for a job step, by means of a 
STEPCAT DD statement. 

key: One or more characters within an item of data that are 
used to identify it or control its use. As used in this 
publication, one or more consecutive characters taken from a 
data record, used to identify the record and establish its order 
A with respect to other records. (See also key field and generic 

y key.) 

key compression: The elimination of characters from the front 
and the back of a key that VSAM does not need to distinguish 
the key from the preceding or following key in an index 
record; reduces storage space for an index. 

key field: A field located in the same position in each record 
of a data set, whose contents are used for the key of a record. 

key sequence: The collating sequence of data records, 
determined by the value of the key field in each of the data 
records. May be the same as, or different from, the entry 
sequence of the records. 

key-sequenced data set: A data set whose records are loaded in 
key sequence and controlled by an index. Records are 
retrieved and stored by keyed access or by addressed access, 
and new records are inserted in the data set in key sequence 
by means of distributed free space. RBAs of records can 
change. 

keyed direct access: The retrieval or storage of a data record 
by use of an index that relates the record's key to its relative 
location in the data set, independent of the record's location 
relative to the previously retrieved or stored record. (See also 
addressed direct access, keyed sequential access, and 
addressed sequential access.) 

keyed sequential access: The retrieval or storage of a data 
record in its key sequence relative to the previously retrieved 
or stored record, as defined by the sequence set of an index. 
(See also addressed sequential access, keyed direct access, 
f, and addressed direct access.) 



mass sequential fansertion: A technique VSAM uses for keyed 
sequential insertion of two or more records in sequence into a 
collating position in a data set: more efficient than inserting 
each record directly. 

mass storage volume: The unit of mass storage in the 38S0 
Mass Storage System. 

master catalog: A key-sequenced data set with an index 
containing extensive data-set and volume information that 
VSAM requires to locate data sets, to allocate and deallocate 
storage space, to verify the authorization of a program or 
operator to gain access to a data set, and to accumulate usage 
statistics for data sets. 

nonunique keys: An alternate key value in a base-cluster's data 
record that equals the alternate key value of another data 
record. When an alternate index is created such that it allows 
nonunique keys, more than one data record might be located 
with the same key value. 

nonVSAM entry: A catalog entry that describes a nonVSAM 
data set. A nonVSAM entry contains the data-set's volume 
serial number and device type. If the data set resides on a 
magnetic tape volume, the entry can also identify the 
data-set's file number. When the data set resides on a 
direct-access device, the operating system obtains further 
information by examining the data set's DSCB (Data Set 
Control Block) in the volume's VTOC (volume table of 
contents). 

object: A logical entity created by VSAM, such as a cluster 
(VSAM data set) and its components, an alternate index and 
its components, a VSAM catalog and its components, a path, 
or a VSAM data space. 

ipige space: A VS2 system data set. A page space is cataloged 
as an entry sequenced cluster (that is, the page space entry is 
similar to a cluster entry, and it points to a data entry). 

password: A unique string of characters stored in a catalog 
that a program or a computer operator at the console must 
supply to meet security requirements before the program 
gains access to a data set. 

path: A data set name for the combination of an alternate 
index and its base cluster, or an alias for a VSAM data set. 

path entry: A catalog entry that contains information about a 
path, and that points to the path's related objects. 

physical record: On a track of a direct-access storage device, 
the space between interrecord gaps. 

pointer: An address or other indication of location. For 
example, an RBA is a pointer that gives the relative location 
of a data record or a control interval in the data set to which 
it belongs. (See abo horizontal pointer and vertical pointer.) 

portability: The ability to use VSAM data sets with different 
operating systems. Volumes whose data sets are cataloged in 
a user catalog can be demounted from storage devices of one 
system, moved to another system, and mounted on storage 
devices of that system. Individual data sets can be transported 
between operating systems using Access Method Services. 

prnnary iqMce aOocaticm: Initially allocated space on a 
direct-access storage device, occupied by or reserved for a 
particular data set. (See also secondary space allocation.) 

prime index: The index component of a key-sequenced data 
set. (See abo index and alternate index.) 

prime key: (See key.) 
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considerations, language 3 1 

continuation cautions 33 

continuing commands 33 

for multivolume data sets (RESETCAT) 132 

job control language 35 

parameter set 31 

terminator 34 
continuation of commands 33 
control-access password 53 

{see also CONTROLPW parameter) 
control area 

in catalogs 77 

Preformatting 58 
control volume pointer entries, converted 48, 1 1 5 
control volumes, OS 45, 1 1 5 

converting to VS AM catalogs 1 1 5 

relationship to other catalogs 45 
CONTROLINTERVALSIZE parameter (DEFINE) 

used to define an alternate index 197 

used to define a cluster 230 
controlling command execution 415 
CONTROLPW parameter 

in ALTER command 156 

in ALTER command (NULLIFY) 160 

in DEFINE command 

ALTERNATEINDEX 197 
CLUSTER 231 
FAGESPACE 273 
PATH 284 
USERCATALOG 302 

nullifying 160 
conventions 

notation 6 

syntactical 3 1 
converting catalog entries 1 1 5 
converting data sets 135 
converting devices for a user catalog 135 
copying 

alternateindexes 55,135 

catalogs 

example 399 
for backup 61,141 
for device conversion 1 3 5 
example 399 

data sets 7,135 

from the catalog recovery area 126 
copying and printing, example of 434 
correcting end-of -data-set information 121 
correcting end-of -key-range information 121 
corrective measures 

for catalog integrity 67 

for data integrity 60 
COUNT parameter 

in PRINT command 385 

in REPRO command 395 
CRA {see catalog recovery area) 
CRA parameter (EXPORTRA) 339 
CRAFILES parameter (RESETCAT) 405 
CRAVOLUMES parameter (RESETCAT) 406 



creating 

alias names 91,181 

alternateindexes 95,169 

an alternate index and path, example of 441 

catalogs 77,297, 

clusters 85,188,191 

data sets 85,91,219 

data spaces 83,291 

entry-sequenced data sets 85 

generation data groups 92,259 

key-sequenced data sets 85 

master catalog 77,297 

nonVS AM data sets 91 

page spaces 92,269 

path 90,281 

portable data sets 1 1 1 

user catalogs 77,297 
CREATION parameter (LISTCAT) 372 

example of output 488 
cross-region sharing 239 
cross-system sharing 239 
CVOLEQUATES parameter (CNVTCAT) 178 
CVOLs (control volumes), OS 48, 11 5 

converting to VSAM catalogs 1 1 5 

relationship to other catalogs 46 
CYLINDERFAULT parameter 51 

in ALTER command 1 65 

in DEFINE command 

used to define an alternate index 208 
used to define a cluster 241 
CYLINDERS parameter 

used to define an alternate index 192 

used to define a cluster 225 

used to define a data space 292 

used to define a page space 270 

used to define a user catalog 299 

D 

data, storage of 41 
data integrity 

backing up data 58 
data organization, specifying 227 
DATA parameter 

in DEFINE command 

ALTERNATEINDEX 211 
CATALOG 306 
CLUSTER 243 
USERCATALOG 307 
in LISTCAT command 370 
data portability 47,59, 1 1 1 
data protection 58 
data security 

and protection 53 
authorization routine 40,53,57 
passwords 53 
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abbreviations, parameter 31,439 
Access Method Services 

commands 29 
functional 30 
modal 31 

guide to 25 

introduction to 29 

invoking 37 
access, read only 53,161,333 
accessibility to secondary extents 59 
adding records through the REPRO command 135 
adding volumes 154 

ADDVOLUMES parameter (ALTER) 154 
ALIAS parameter 91 

in DEFINE command 181 

in DELETE command 316 

in LISTCAT command 370 
ALL parameter (LISTC AT) 371 

example of output 478 
ALL subparameter (EXPORTRA) 340 
ALL subparameter (RESETCAT) 405 
allocating space 

by range of key values 233 

for a catalog 77 

on unmounted volumes 72 
allocation 

dynamic 35,72 

of a catalog recovery area (CRA) 83 

of a volume 42 

of catalog's space 77 

of user catalogs 47 
ALLOCATION parameter (LISTCAT) 371 

example of output 483 

(see also BUFFERSPACE parameter) 
ALTER command 99,151 

allocation parameters 1 52 

alternate index and path attributes 152 

catalog parameter 156 

entry types to which each parameter applies 153 

examples 167 

format 151 

generation-data-group attribute parameters 152 

name parameters 152 

parameter summary table 153 

order of catalog use 100 

Parameters 1 54 

Optional parameters 1 54 
Required parameters 1 54 

protection and integrity parameters 152 

removing VSAM ownership of a volume 42,63 

volume cleanup 63,101 
altering catalog entries 99 
alternate index 

backing up (copying) 135 

building 95 

defining 88,185 

deleting 105,316 

exporting 113 

importing 113 

listing its catalog entry 103 

printing its contents 144 



alternate name 
creating 91,181 

examples 183 
deleting 105,316 
example 326 
alternate output data sets 37 
ALTERNATEINDEX parameter 88 
in DEFINE command 185 
in DELETE command 3 1 6 
in LISTC AT command 370 
amendments, summary of 21 
AN, print chain option 419 
AREAS parameter (FARM) 419 
ATTEMFTS parameter 56 
in ALTER command 154 
in DEFINE command 

ALTERNATEINDEX 195 
Catalog 300 
CLUSTER 228 
PAGESPACE 272 
PATH 282 

USERCATALOG 300 
note for TSO users 300 
attributes 85 
altering 99 
changing 99,537 
defining 72,85 
nullifying 162 
AUTHORIZATION parameter 
in ALTER command 155,160 
in DEFINE command 

ALTERNATEINDEX 195 
CLUSTER 228 
PAGESPACE 272 
PATH 283 

USERCATALOG 300 
nullifying 160 
Auxiliary Storage Management 276 
authorization to process a data set 
passwords 53 
RACE protection 57 
user-security-verification routine 57 

B 

backing up catalogs 61 
backing up data sets 58,135 
beginning location 

in PRINT command 383 

in REPRO command 392 
BIND parameter 51 

in ALTER command 164 

in DEFINE command 

used to define an alternate index 208 
used to define a cluster 241 
blanks 6,32 
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used to define a cluster 85,219 

allocation parameters 222 

catalog parameter 247 

components parameters 243 

data organization parameters 227 

entry type parameter 222 

examples 247 

format 219 

model parameter 235 

name parameter 222 

parameters, summary of 222 
optional paramters 228 
required parameters 224 

parameters that apply only to key-sequenced 
clusters 224 

protection and integrity parameters 223 

slpecifying information for 85,219 
used to define a data space 83,291 

allocating the volume 83 

allocation parameters 291 

catalog parameter 293 

example 295 

format 291 

optional parameters 293 
required parameters 291 
used to define a generation data group 92,259 

example 262 

format 259 

parameters 259 
used to define a nonVSAM data set 91,265 

example 268 

format 265 

parameters 265 

optional parameters 266 
required parameters 265 
used to define a page space 92,269 

allocation parameters 235 

catalog parameter 278 

examples 279 

format 269 

model parameter 275 

name parameter 269 

parameter summary 269 
optional parameters 272 
required parameters 270 

parameters that apply only to page spaces 270 

protection and integrity parameters 270 
used to define a path 90,281 

allocation parameter 281 

catalog parameter 288 

example 289 

format 281 

model parameter 285 

name parameter 282 

parameter summary 281 
optional parameters 282 

required parameters 282 

protection parameters 281 

update parameter 282 



used to define a user catalog 77,297 
allocation parameters 298 
catalog parameter 298,307 
componenti parameters 298,306 
entry type parameters 298 
examples 308 
format 297 

model parameter 298,303 
name parameter 299 
parameters, summary of 298 
optional parameters 300 
required parameters 299 
protection and integrity parameters 298 
How parameters are organized 74 
defining 71 
alias 91,181 
alternate index 88,185 
catalog 77,297 
cluster 85,219 
data space 83,291 
generation data group 92,259 
NONVSAM data set 91,265 
page space 92,269 
path 90,281 
user catalog 77,297 
DELETE command 3 1 5 
catalog cleanup 665,322 
examples 321 
format 315 

kinds of catalog entries you can delete 105 
parameters 315 

optional parameters 316 
required parameters 315 
removing VSAM ownership of a volume 41 
deleting 105 

(see also DELETE command) 
catalog entries 105 
a data set 106 

examples of 321 
a VSAM catalog and its objects, example of 449 
regardless of retention date (see PURGE parameter) 
descriptive information, specifying 
for an alternate index 88 
for a cluster 85 
DESTAGEW AIT parameter 51 
in ALTER command 157 
in DEFINE command 

ALTERNATEINDEX 198 
catalog 302 
CLUSTER 231 
USERCATALOG 302 
destaging attributes 51 

(see also DESTAGEW AIT and NODESTAGEWAIT) 
destaging to mass storage 51 
device conversion for a user catalog 135 
device independence of VSAM data sets 42 
device type translate table 470 
DEVICETYPE subparameter 
in IMPORT command 351 
in IMPORTRA command 362 
DEVICETYPES parameter (DEFINE NONVSAM) 265 
direct-access space allocation 72 
DISCONNECT parameter (EXPORT) 331 
displaying catalog information {see LISTCAT command) 
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changing attributes 

allocation 152 

generation data group 1S2 

name 1 52 

protection 152 

VSAM master catalog 535 
changing a volume's serial number 64 
changing the attributes of a VSAM master catalog 535 
CHARACTER parameter (PRINT) 382 
CHECKID parameter (CHKLIST) 173 
checkpoint data set 147 
checkpoint, tape data sets open at 147 
CHKLIST command 147,173 

examples 174 

format 173 

listing tape volumes mounted at checkpoint 147 

parameters 173 

optional parameters 173 
required parameters 173 

sample output from 507 
CHKPT JCL parameter 493 
cleanup 

catalog 65,315 

volume 63 
cluster 

backing up (copying) 58,135 

defining 85,219 

deleting 105,315 

exporting 111,331 

listing its entry 103,369 

importing 1 1 1,347 

printing its contents 1 44, 3 8 1 

verifying its end-of-file values 121,413 
CLUSTER parameter 

in DEFINE command 219 

in DELETE command 316 

in LISTCAT conamand 370 
cluster type, specifying 222 
CNVTCAT command 115,177 

examples 179 

format 178 

parameters 178 
CODE parameter 55 

in ALTER command 156 

in DEFINE command 

ALTERNATEINDEX 196 
CATALOG 301 
CLUSTER 229 
PAGESPACE 273 
PATH 284 
USERCATALOG 301 

nullifying 160 
command continuation 33 
command execution, controlling 415 
command reference summary 509 
command statement syntax 3 1 



commands 

ALTER 99,151 

BLDINDEX 95,169 

CHKLIST 147,173 

CNVTCAT 115,177 

continuation of 33 

DEFINE 

ALIAS 91,181 

ALTERNATEINDEX 88,185 
CLUSTER 85,219 

for an entry-sequenced cluster 227 
for a key-sequenced cluster 224,227 
for a relative-record cluster 227 
GENERATIONDATAGROUP 92,259 
NONVSAM 91,265 
PAGESPACE 92,269 
PATH 90,281 
SPACE 83,291 
USERCATALOG 77,297 

DELETE 105,315 

DO 31,417 

END 31,417 

EXPORT 111,331 

EXPORTRA 123,339 

functional 30 

general structure 31 

guide to 25 

IF 31,416 

IMPORT 111,347 

IMPORTRA 123,361 

introduction 29 

LISTCAT 103,369 

LISTCRA 125,377 

modal 31,415 

not allowed under TSO 39 

parameter set 3 1 
reference summary 509 

PARM 31,418 

PRINT 144,381 

REPRO 135,391 

RESETCAT 129,405 

SET 418 

VERIFY 121,413 

structure of 3 1 " 

terminator 34 

types 29 
commas 32 
comments 32 
COMPARE parameter (LISTCRA) 378 

example of output 505 
components parameters (DEFINE) 

used to define an alternate index 211 

used to define a catalog 306 

used to define a cluster 243 
concatenated DD statements 35 
condition codes 415 
conditional command execution 

using LASTCC 418 

using MAXCC 418 
conditional statements 415 
CONNECT parameter (IMPORT) 347 
connecting a user catalog to the master catalog 45 ,9 1 , 1 1 1 
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exporting 

a base cluster and its alternate index, example of 443 

a catalog's data sets 59 

an entry 1 1 1 

a user catalog 47 

examples 335 
EXPORTRA command 339 

copying an entry from the catalog recovery area 126 

example of 342 

format 341 

pararheters 293 

optional parameters 341 
required parameters 339 
EXTERN ALSORT parameter (BLDINDEX) 1 7 1 



F 



33 



field continuation rules 
fields 

continuing 33 
separators with 33 
FILE parameter 

{see also INFILE parameter and OUTFILE parameter) 
in ALTER command 1 57 
in DEFINE command 

to define an alternate index 199 

to define a cluster 232 

to define a data space 293 

to define a page space 274 

to define a path 285 

to define a user catalog 302 
in DELETE command 3 1 8 
in VERIFY command 413 
FILE subparameter 

in IMPORT command 351 
in IMPORTRA command 363 
FILESEQUENCENUMBERS parameter (DEFINE 

NONVSAM) 266 
FOR parameter 

in ALTER command 165 
in DEFINE command 

ALTERNATEINDEX 209 

catalog 305 

CLUSTER 242 

GENERATIONDATAGROUP 260 

NONVSAM 267 

PAGESPACE 276 

PATH 287 

USERCATALOG 305 
FORCE parameter 

in DELETE command 3 1 9 
in EXPORTRA command 341 
format of commands 

ALTER command 151 ALTER command 151 
BLDINDEX command 169 
CHKLIST command 173 
CNVTC AT command 177 
DEFINE command 

ALIAS 181 

ALTERNATEINDEX 185 

CLUSTER 219 

GENERATIONDATAGROUP 259 

NONVSAM 265 

PAGESPACE 269 

PATH 281 

SPACE 291 

USERCATALOG 297 



DELETE command 315 

DO 417 

END 417 

EXPORT command 331 

EXPORTRA command 339 

IF 416 

IMPORT command 347 

IMPORTRA command 361 

LISTCAT command 369 

LISTCRA command 377 

FARM 418 

PRINT command 381 

REPRO command 391 

RESETCAT command 405 

SET 418 

VERIFY command 413 
format of LISTCAT output 47 1 
format of LISTCRA output 493 
format of printed data with PRINT command 382 
Format 1 DSCB 42,63 
Format 4 DSCB 42,63 
FREESPACE parameter 

in ALTER command 158 

in DEFINE command 

used to define an alternate index 200 
used to define a cluster 232 
FROMADDRESS parameter 

in PRINT command 383 

in REPRO command 393 
FROMKEY parameter 

in PRINT command 383 

in REPRO command 392 
FROMNUMBER parameter 

in PRINT command 383 

in REPRO command 393 
FULL parameter (FARM) 419 
functional commands 30 

G 

GE (greater than or equal) 416 
generated names 43 

for suballocated data spaces 43 

for unique data spaces 43 

for VSAM data and index components 43 
generating trace tables 418 
generation data set 259 

cataloging, example of 262 
GENERATIONDATAGROUP parameter 

in DEFINE command 259 
example 262 

in DELETE command 316 

in LISTCAT command 370 
generic (qualified) names 48 

in ALTER command 100 

in DEFINE command 72 
example 256 

in DELETE command 109 

in LISTCAT command 103 
GRAPHICS parameter 419 
GT (greater than) 416 
guide to Access Method Services 25 
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data set 

allocation 72 

backup copy 58,111,135 

catalog entry 71 

cataloging 71,85,91 

copying 59,135 

comparison between types of 117 

creating 67,85,91 

defining 67,85,91 

deleting 105 

entry-sequenced 85 

generated names 43 

generation 259 

key-sequenced 85 

listing 144 

loading records into 141 

NONVSAM 91 

organization 43,227 

output 37 

portability 59,111 

Preformatting 58 

reorganizing 142 

tape, open at checkpoint 147 

transporting 58,111 

unique 77,242,250 

using qualified names that identify the catalog 45,48 
data-set access 333 

data-set security bits in Format- 1 DSCB 43 
data-set type, specifying 91,227 
data space 

allocating the volume for 83,291 

defining 291 
examples 293 

extending 291 

pagespace in 269 

VSAM objects in a 42,84 
data sets, VSAM 42,84 
data spaces on a volume 42 
data structure, VSAM 41 
D AT ASET parameter (VERIFY) 413 
DD statements 32 {see JCL) 

for Access Method Services jobs 36 

for JOBCAT and STEPCAT catalogs 47,72 

for output data sets 37 

for RESETCAT work file 132 

for the BLDINDEX sort workfiles 97 
debugging tool 418 
default margins 31 
default output data set 37 
define a user catalog, example of 423 
define nonVSAMdata sets, example of 430 
define VSAM data sets, example of 426 



DEFINE command 71 

how parameters are organized 74 

job control language statements for 72 

naming entries to prevent duplicate names 72 

order of catalog use 73 

used to define an alternate index 88,185 

catalog parameter 214 

components parameters 21 1 

data integrity parameters 190 

example 216 

format 185 

index parameters 205 

model parameter 202 

name parameter 1 89, 1 9 1 

optional parameters 195 

parameters, summary of 189 

required parameters 191 

protection parameters 190 

specifying information for 88, 1 85 
used to define an alternate name (alias) 91,181 

example 181 

format 181 

parameters 181 

optional parameters 181 
required parameters 181 
used to define a catalog 

allocation parameters 281 

catalog parameter 288 

example 289 

format 281 

model parameter 285 

name parameter 282 

parameter summary 281 
optional parameters 282 
required parameters 282 

protection parameters 281 

update parameter 282 
used to define a user catalog 77,297 

allocation pzirameters 298 

catalog parameter 298,307 

components parameters 298,306 

entry type parameters 298 

examples 308 

format 297 

model parameter 298,303 

name parameter 299 

parameters, summary of 298 
optional parameters 300 
required parameters 299 

protection and integrity parameters 298 
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K 

key 

allocating space on volumes by key range 233 

(see also KEYS parameter) 
key-pointer pairs of an alternate index 95 

building 95 

defining 95 
key-sequenced data set 

definition 41 

examples of defining 249,250,254 

specification of 227 
KEYRANQES parameter (DEFINE) 

used to define an alternate index 200 

used to define a cluster 233 
KEYRANGES subparameter (IMPORT) 200 
KEYS parameter 

in. ALTER command 158 

in DEFINE command 

used to define an alternate index 202 
used to define a cluster 234 
keyword parameters 3 1 
kinds of catalog entries you can delete 105 



language considerations 3 1 
continuation cautions 33 
continuing commands 33 
parameter set 31 
terminator 34 
last condition code inee LASTCC) 
LASTCC 
in IF 416 
in5ET 418 
LE (less than or equal) 416 
levels in LISTCAT command 372 
LEVEL parameter (LISTCAT) 372 
LIMIT parameter (DEFINE 

GENERATIONDATAGROUP) 259 
LIST parameter (CNVTCAT) 178 
LISTCAT command 103,369 
examples 375 
format 369 

interpreting output from 453 
JCL required for 47 1 
order of catalog use 103 
parameters 369 

optional parameters 369 
required parameters 369 
sample output from 471 
LISTCAT output 

and Access Method Services messages 473 
keywords 

description of 458 
list of 453 
job control language for 471 
listing, examples of 

LISTCAT output 471 

LISTCAT ALL output 478 

LISTCAT ALLOCATION output 483 

LISTCAT CREATION/EXPIRATION output 488 

LISTCAT HISTORY output 486 

LISTCAT SPACE ALL output 477 

LISTCAT VOLUME output 475 



LISTCRA command 377 
example 379 
examples of output 495 
format 377 

listing the catalog recovery area's contents 123 
parameters 377 

optional parameters 377 
required parameters 377 
types of listing 496 
LISTCRA output 495 
description of 495 . 
listing, examples of 

LISTCRA DUMP COMPARE output 500 
LISTCRA DUMP NOCOMPARE output 502 
LISTCRA NAME COMPARE output 504 
LISTCRA NAME NOCOMPARE output 500 
listing catalog entries 103 
examples of 375 
examples of output 47 1 
listing tape volumes mounted at checkpoint 147 
listing the catalog recovery area's contents 125 

examples of output 495 
loading catalogs (unload/reload) 142 
loading records into a data set 137 
Preformatting control areas 58 
REPRO command 391 
loading VS AM data sets 1 37 
lower case, in notation conventions 6 
LT (less than) 416 

M 

making a copy of a data set 59 

making a user catalog available 47 

MARGINS parameter (FARM) 420 

margins, default 32 

Mass Storage System, IBM 3850 51 

mass storage volume 51 

master catalog 45 

{see also user catalog) 

backing up 141 

cataloging nonVSAM data sets 91 

changing the attributes of 535 

creating a 77 

deleting restriction 106 

improving availability of 61 

order of catalog search 
ALTER 100 
BLDINDEX 97 
DEFINE 73 
DELETE 108 
LISTCAT 103 

preventing duplicate names in 72 

protecting 60 

reloading 142 

relationship to user catalogs 44,77 

unloading 142 

using a backup copy 61 
master password 53 

(see also MASTERPW parameter) 
MASTERCATALOG parameter 

in CNVTCAT command 178 

in DEFINE command (defines user catalog) 77 
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DO, in DO-END command sequence 417 

examples 421 

format 417 
DSCB (data set control block) 

volume cleanup 63 

VSAM volume ownership 42 
DUMMY subparameter (REPRO) 391 
dummy records 391 
DUMP parameter 

in LISTCRA command 378 
example of output 502 

in PRINT command 381 
dump points 419 
DUMP/RESTORE program, lEHDASDR 

backing up a catalog 61 

timestamp updating 42 
dumping 

a catalog and its data sets 61 

a volume owned by VSAM 61 
duplicate names in a catalog, preventing 72 
dynamic allocation 35,72 

E 

ellipses, in notation conventions 6 

ELSE clause, in IF-THEN-ELSE command sequence 417 

EMPTY parameter 

in ALTER command 157 

in DEFINE command 

used to define a generation data group 259 
END, in DO-END command sequence 417 

examples 421 

format 417 
end-of-file values, restoring a cluster's 121 
ending location 

in PRINT conunand 384 

in REPRO command 394 
enhancements, sununary of 21 
ENTRIES parameter (LISTCAT) 372 
ENTRIES subparameter (EXPORTRA) 340 
entryname/password parameter 

in ALTER command 154 

in DELETE command 315 

in EXPORT command 331 
entry-sequenced data set 41,85 

compared with key-sequenced 41,85 

examples of defining 249 

specification of 86 
entry-type parameters (LISTCAT) 370 
entry-types each ALTER parameter applies to 153 
ENVIRONMENT subparameter (REPRO) 391 
EQ (equal) 416 
ERASE parameter 

erasing data on a staging drive 5 1 

in ALTER command 157 

in DEFINE command 

used to define an alternate index 198 
used to define a cluster 231 

in DELETE command 318 

in EXPORT command 332 

in IMPORT command 350 
erasing (deleting) a data set 105 

(see also DELETE command and ERASE parameter) 



estimating the space requirements 
for a catalog 80 

example of 308 

worksheet for 81 
for the BLDINDEX sort workfiles 96 
examples of 

Access Method Services jobstream 423 
ALTER command 167 
BLDINDEX command 172 
catalog unload/reload 402 
CHKLIST command 174,507 
CNVTCAT command 179 
copying a catalog 399 
DEFINE command 

for an alias 183 

for an alternate index 216 

for a catalog 308 

for a cluster 248 

for a data space 295 

for a generation data group 262 

for a nonVSAM data set 268 

for a page space 279 

for a path 289 

for a user catalog 308 
DELETE command 321 
DO-END 421 
EXPORT command 335 
EXPORTRA conwnand 342 
IF-THEN-ELSE 421 
IMPORT command 356 
IMPORTRA command 366 
jobs using Access Method Services commands 423 
LISTCAT command 375 
LISTCAT output 471,490 
LISTCRA command 379 
LISTCRA output 495 
PRINT command 386 
PRINT output 388 
REPRO command 396 
RESETCAT command 408 
SET 421 

VERIFY command 414 
EXCEPTIONEXIT parameter 
in ALTER command 1 57 
in ALTER (NULLIFY) 160 
in DEFINE command 

used to define an alternate index 199 

used to define a cluster 232 
execution, controlling 415 
expiration date, nullifying 161 

(sec also FOR parameter and TO parameter) 
EXPIRATION parameter (LISTCAT) 374 

example of output 488 
EXPORT command 331 
examples 335 
format 331 
parameters 331 

optional parameters 332 

required parameters 331 
transporting alternate indexes 59 
transporting data sets 59 
transporting user catalogs 47 
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nonVSAM data sets 

and the catalog's update password 56,80 

cataloging 91 
example 268 

copying 59 

deleting 105 

example of defining 268 

listing catalog entries for 103 

passwords for 56 

printing 144,381 
NONVSAM parameter 

in DEFINE command 91,265 

in DELETE command 3 1 6 

in LISTCAT command 370 
NOPURGE parameter 

in DELETE command 320 

in EXPORT command 333 

in IMPORT command 355 
NORECLAIM parameter 

in DEFINE command 

used to define an alternate index 205 
used to define a cluster 238 
NOREPLACE parameter (REPRO) 390 
NOREPLICATE parameter (DEFINE) 

used to define an alternate index 206 

used to define a cluster 238 
NOREUSE parameter 

in DEFINE command 

used to define an alternate index 206 
used to define a cluster 238 

in REPRO command 394 
normal output data set 37 
NOSAVRAC parameter 

in IMPORT command 355 

in IMPORTRA command 364 
NOSCRATCH parameter 

in DEFINE command 

used to define a generation data group 260 

in DELETE command 320 
catalog cleanup 56,320 

modified in ALTER command 163 
notation conventions 6 
NOSWAP parameter (DEFINE PAGESPACE) 270 

in DEFINE PAGESPACE command 276 

in DEFINE PAGESPACE example 279 
NOTUSABLE parameter (LISTCAT) 374 
NOUPDATE parameter 

in ALTER command 165 

in DEFINE command 287 
NOUPGRADE parameter 

in ALTER command 166 

in DEFINE command 211 
NOTRECOVERABLE parameter (DEFINE) 304 
NOWRITECHECK parameter 

in ALTER command 166 

in DEFINE command 

ALTERNATEINDEX 211 
CLUSTER 243 
USERCATALOG 306 
NULLIFY parameter (ALTER) 160 
NUMBERED parameter (DEHNE) 228 

o 

objects (VSAM) 

in a data space 41,84 
space assignment to 85 



OBJECTS parameter 

in IMPORT command 351 

in IMPORTRA command 362 
OFF parameter (FARM) 419 
operator entering passwords 56 

{see also CODE parameter and ATTEMPTS parameter) 
optimizing the performance of catalog unload/reload 144 
optional allocation parameters 

for an alternate index 190 

for a cluster 223 
OR sign ( I ), in notation conventions 6 
order of catalog use 

ALTER 100 

BLDINDEX 97 

DEFINE 73 

DELETE 108 

LISTCAT 103 
ORDERED parameter (DEFINE) 

used to define an alternate index 203 

used to define a cluster 236 
ORDERED subparameter (IMPORT) 353 
OS CVOLs (control volumes) 

converting to VSAM catalogs 1 1 5 

relationship to other catalogs 44 
OUTDATASET parameter 

in EXPORT command 332 

in IMPORT command 349 

in REPRO command 392 
OUTFILE parameter 

in BLDINDEX command 170 

in CHKLIST command 173 

in EXPORT command 332 

in EXPORTRA command 339 

in IMPORT command 348 

in IMPORTRA command 364 

in LISTCAT command 374 

in LISTCRA command 378 

in PRINT command 384 

in REPRO command 392 
output data sets 

default for listing 37 

job control language for 37,499 

requirements 37 
overwriting {see ERASE parameter) 
OWNER parameter 

in ALTER command 161 

in ALTER (NULLIFY) 161 

in DEFINE command 
note for TSO users 236 
used to define an alternate index 204 
used to define a catalog 304 
used to define a cluster 236 
used to define a generation data group 260 
used to define a nonVSAM data set 267 
used to define a page space 275 
used to define a path 286 
ownership bit in Format 4 DSCB 42 
ownership, VSAM volume 42 

removing 42 
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H 

HEX parameter (PRINT) 382 
HISTORY parameter (LISTCAT) 371 

example of output 486 
HN, print chain option 419 
how an alternate index is built 95 
how to use one object as a model for another object 75 
hyphens 33 

I 

I/O buffer 

and the ALTER command 155 

and the ALTERNATEINDEX command 196 

and the DEFINE command 229,301 

space for 196,229,301 
identifying the catalog's volume 80 
lEHDASDR DUMP/RESTORE program 

backing up a catalog 61 

changing a volume's serial number 64 
IF-THEN-ELSE command sequence 416 

examples 420 

format 416 
IGNORE parameter (RESETCAT) 406 
IMBED parameter (DEHNE) 

used to define an alternate index 200 

used to define a cluster 233 
INTOEMPTY parameter 

in IMPORT command 350 
IMPORT command 59, 1 1 1 ,347 

examples 356 

format 347 

parameters 347 

optional parameters 350 
required parameters 347 

transporting alternate indexes 59 

transporting data sets 59 

transporting user catalogs 47 
importing 

a catalog's data sets 59 

an entry 111 

a user catalog 47 

examples 356 
IMPORTRA command 361 

example of 366 

format 361 

parameters 361 

restoring the catalog entry that was obtained using the 
EXPORTRA command 128 
INDATASET parameter 

in CNVTC AT command 177 

in IMPORT command 348 

in PRINT command 381 

in REPRO command 391 
index, alternate (see alternate index) 
INDEX parameter 

in DEFINE command 

used to define an alternate index 213 
used to define a catalog 307 
used to define a cluster 245 
used to define a user catalog 307 

in LISTCAT command 370 
INDEXED parameter (DEFINE) 227 



INFILE parameter 

in BLDINDEX command 169 

in CHKLIST command 173 

in CNVTC AT command 177 

in EXPORT command 332 

in IMPORT command 347 

in IMPORTRA command 361 

in LISTCRA command 377 

in PRINT command 381 

in REPRO command 391 
INFILE subparameter (EXPORTRA) 340 
INHIBIT parameter (ALTER) 1 58 
INHIBITSOURCE parameter (EXPORT) 333 
INHIBITTARGET parameter (EXPORT) 333 
input record margins 32 
integrity of data 

passwords 53 
INTERN ALSORT parameter (BLDINDEX) 1 7 1 
interpreting LISTCAT output listings 453 

description of keyword fields 458 

LISTCAT output keywords 453 

LISTCAT output examples 471 
interpreting LISTCRA output 495 
introduction 29 
invoking Access Method Services 37,527 

as a job or job step 38 

from a processing program 40,527 

from a TSO terminal 34 

invocation from a PL/I program 532 
ISAM data sets 

cataloging 91 

converting 135 

copying 135 

deleting 105 

listing catalog entries for 103 

printing 144 
italics, in notation conventions 6 



JCL 

allocating user catalogs 47 
catalog unload/reload 144 
CHKLIST command 174 
DEFINE command 72 
dynamic allocation 35,72 
for an output data set 37 

example 471 
identifying VS AM data sets or volumes 42 
invoking Access Method Services 37 

examples of use 423 
JOBCAT DD statement 47 
LISTCAT command 471 
passwords for nonVSAM data sets 56 
RESETCAT command 133 
STEPCAT DD statement 474 
to be avoided 493 
to define an entry 72 
JOBCAT catalog 

DD statement for 47 
order of catalog use 

ALTER 100 

BLDINDEX 97 

DEHNE 73 

DELETE 108 

LISTCAT 103 
jobstep, invoking Access Method Services as a 37 
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READPW parameter 

in ALTER command 1 6 1 

in DEFINE command 

for an alternate index 204 
for a catalog 304 
for a cluster 237 
for a page space 276 
for a path 286 

nullifying 161 
record 

{see also RECORDSIZE parameter) 

replacement, example of 437 
RECORDS parameter (DEFINE) 

used to define an alternate index 192 

used to define a catalog 299 

used to define a cluster 225 

used to define a data space 292 

used to define a page space 270 
RECORDSIZE parameter 

in ALTER command 162 

in DEFINE command 

to define an alternate index 204 
to define a cluster 237 
to define a data space 292 
recoverable, making the master catalog 66 
RECOVERABLE parameter (DEFINE) 304 
recovery, catalog 66,123 

other recovery methods 66 

the catalog recovery area 123 
recovery area (see catalog recovery area) 
RECOVERY parameter (DEFINE) 

used to define an alternate index 208 

used to define a cluster 241 
regaining access to data 67 
regions sharing data 206,239 
RELATE parameter (DEFINE) 88, 192 
related publications 5 
reloading a catalog 142 
REMOVE VOLUMES parameter (ALTER) 162 

volume cleanup 65 
removing volumes 162 

removing VSAM ownership of a volume 43,65 
renaming data sets 

in ALTER command 99,151 

in IMPORT command 353 
reorganizing data sets 135 
REPLACE parameter (REPRO) 393 
REPLICATE parameter (DEFINE) 

used to define an alternate index 205 

used to define a cluster 238 
REPRO command 135,391 

catalog unload/reload 142 

optimizing the performance of 144 

converting device of user catalog 135 

example 396 

format 391 

parameters 391 

optional parameters 392 
required parameters 391 
required publications 4 
requirements, storage 

VSAM catalog 77 
reserving volumes {see CANDIDATE parameter, VOLUME 

parameter, and ADDVOLUMES parameter) 
reset condition codes 418 
RESETCAT command 405 



examples 408 

format 405 

function 129 

JCL Requirements 133 

Multivolume data sets 132 

parameters 405 

optional parameter 405 
required parameter 405 

reference summary 525 

requirements 1 3 1 

WORKHLE Space Requirements 132 
respecifying attributes 99, 1 5 1 
Resource Access Control Facility (RACE) 57 

when moving entries 1 1 1 

inEXPORTRA 128 

in ALTER 160 
RESTORE program, lEHDASDR 61 
restoring a cluster's end-of-file values 121 
restoring catalog entries after system failure 123 

catalog recovery area contents 123 
listing the 124 

copying a catalog entry from the catalog recovery 
area 125 

examples of 366 

procedure for 123 

resetting catalog entries 129 

restoring the catalog entry that was obtained using the 
EXPORTRA command 128 
retention date for data set 

(see also FOR parameter and TO parameter) 

nullifying 161 

overriding {see PURGE parameter) 
RETENTION parameter (ALTER) 1 6 1 
reusable data sets 238 
REUSE parameter 

in DEFINE command 

used to define an alternate index 206 
used to define a cluster 238 

in REPRO command 394 
RN, print chain option 419 
rules of continuation 33 



SAM data sets 

converting 135 

copying 135 

deleting 105 

listing catalog entries for 103 

printing 144 
SAM to VSAM conversion 135 
SAVRAC parameter 

in IMPORT command 355 

in IMPORTRA command 364 
SCRATCH parameter 

in DEFINE command 

used to define a generation data group 260 

in DELETE command 320 

modified in ALTER command 163 
searching catalogs, order of 

with the ALTER command 100 

with the BLDINDEX command 97 

with the DEFINE command 73 

with the DELETE command 108 

with the LISTCAT command 103 
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MASTERPW parameter 

in ALTER command 159 

in DEFINE command 

ALTERNATEINDEX 202 
CLUSTER 235 
PAGESPACE 274 
PATH 285 
USERCATALOG 303 

in EXPORTRA command 341 

in LISTCRA command 378 

in RESETCAT command 406 

nullifying 161 
MAXCC parameter 

in IF 416 

in SET 418 
maximum condition code 416,418 
memory (see virtual storage) 
merging VS AM data sets 135 
migration of passwords 54 
MISCOMPARES messages 68,495 
mismatches between catalog and CRA records 67 
modal commands 31 

not allowed from TSO terminal 39 
MODEL parameter 

to define an alternate index 202 

to define a catalog 303 

to define a cluster 235 

to define a page space 275 

to define a path 285 

to define a user catalog 303 
modeling 75 

alternate indexes 202 

clusters 235 
example 256 

data components 75 

index components 75 

page spaces 275 

paths 285 

user catalogs 303 
example 312 
modify sequence of execution 416 
modifying catalog information (see ALTER command) 
moving entries 111 

MODULE subparameter (ALTER) 160 
moving data sets between systems 61,111 
moving user catalogs between systems 47, 1 12 

N 

name parameter (ALTER) (see entryname parameter) 
NAME parameter 

in DEFINE command 

used to catalog a nonVSAM data set 265 

used to identify an alternate index 191 

used to identify a catalog 299 

used to identify a cluster 224 

used to identify a generation data group 259 

used to identify a page space 270 

used to identify a path 282 
in LISTC AT command 371 

example of output 471 
in LISTCRA command 378 

example of output 500,504 
names, generated 41 



names, generic (or qualified) 

in ALTER command 100 

in DEFINE command 72 
example 256 

in DELETE command 109 

in LISTC AT command 103 
naming 

clusters 224 

data components 224 

entry-sequenced data sets 224 

index components 224 

key-sequenced data sets 224 

master catalog 72 • 

page spaces 270 

paths 282 

user catalogs 72,259 
NE (not equal) 416 
NEWNAME parameter (ALTER) 1 59 
NEWNAME subparameter (IMPORT) 353 
NOCOMPARE parameter (LISTCRA) 378 

example of output 500,502 
NODESTAGEWAIT parameter 51 

in ALTER command 157 

in DEFINE command 

ALTERNATEINDEX 198 
catalog 302 
CLUSTER 231 
USERCATALOG 302 
NOEMPTY parameter 

in ALTER command 157 

in DEFINE command 

used to define a generation data group 260 
NOERASE parameter 

in ALTER command 1 57 

in DEFINE command 

used to define an alternate index 198 
used to define a cluster 231 

in DELETE command 318 

in EXPORT command 332 

in IMPORT command 350 

not erasing data on a staging drive 5 1 
NOFORCE parameter 

in DELETE command 319 

in EXPORTRA command 341 

NOIGNORE parameter (RESETCAT) 406 
NOIMBED parameter (DEFINE) 

used to define an alternate index 200 

used to define a cluster 233 
NOINHIBITSOURCE parameter (EXPORT) 333 
NOINHIBITTARGET parameter (EXPORT) 333 
NOLIST parameter (CNVTCAT) 178 
NONE subparameter (EXPORTRA) 341 
NONE subparameter (RESETCAT) 405 
NONINDEXED parameter (DEFINE) 228 
NONSPANNED parameter (DEFINE) 240 
NONUNIQUEKEY parameter 

in ALTER command 160 

in DEFINE command 210 
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Time Sharing Option (TSO) 49 

abbreviated LISTCAT listings 371,490 

invoking Access Method Services from a terminal 39 
timestamp updating 40 
TN, print chain option 419 
TO parameter 

in ALTER command 165 

in DEFINE command 

used to define an alternate index 209 
used to define a catalog 305 
used to define a cluster 242 
used to define a generation data group 260 
used to define a nonVSAM data set 267 
used to define a page space 276 
used to define a path 287 
TOADDRESS parameter 

in PRINT command 384 

in REPRO command 394 
TOKEY parameter 

in PRINT command 384 

in REPRO command 394 
TONUMBER parameter 

in PRINT command 384 

in REPRO command 394 
TRACE parameter (PARM) 419 
tracing outputs 419 
TRACKS parameter (DEFINE) 

used to define an alternate index 192 

used to define a catalog 299 

used to define a cluster 225 

used to define a data space 292 

used to define a page space 270 
Translate Table, device type 470 
transporting data sets between systems 58,111 
TSO (Time Sharing Option) 49 

abbreviated LISTCAT listings 371,490 

invoking Access Method Services from a terminal 39 
types of commands 29 

u 

underlining, in notation conventions 6 
UNINHIBIT parameter (ALTER) 1 58 
unique data set 

defining 242 

space for 71 
UNIQUE parameter (DEFINE) 

used to define an alternate index 209 

used to define a cluster 242 
UNIQUEKEY parameter 

in ALTER command 165 

in DEFINE command 210 
unload/reload, catalog 142 

optimizing the performance of 144 
unloading a catalog 142 
UNORDERED parameter (DEFINE) 

used to define an alternate index 203 

used to define a cluster 236 
UNORDERED subparameter (IMPORT) 353 
update access 53 
UPDATE parameter 

in ALTER command 165 . 

in DEFINE command 287 ^ 
update password 53 

nonVSAM data sets and the catalog's update password 80 

{see also UPDATEPW parameter) 



UPDATEPW parameter 
in ALTER command 1 66 
in DEFINE command 

ALTERNATEINDEX 210 
catalog 305 
CLUSTER 243 
PAGESPACE 277 
PATH 288 

USERCATALOG 305 
nullifying 161 
updating a backup copy of a catalog 62 
updating a data set's end-of-file information 121 
updating timestamps 43 
UPGRADE parameter 
. in ALTER command 166 
in DEFINE command 211 
upper case, in notation conventions 6 
USAR (see user-security authorization record) 
user catalog 

{see also master catalog) 
allocating 77 
altering 99 
backing up 62,142 
calculating space for 77,80 
cataloging nonVSAM data sets 91 
connecting to master catalog (IMPORT) 112 
creating a 297 

examples 308 
defined on mass storage volume 77 
deleting 105 

disconnecting from master catalog (EXPORT) 1 12 
exporting 1 12 
importing 1 1 1 
JCL 47,72 
listing 103 
order of use 
ALTER 100 
BLDINDEX 97 
DEFINE 73 
DELETE 108 
LISTCAT 103 
preventing duplicate names 72 
protecting 60 

relationship to master catalog 45,77 
reloading 142 
stnictui'c 44 
transporting 65 
unloading 142 
using a backup copy 62 
volume portability 1 1 1 
USERCATALOG parameter 
in DEFINE command 297 
in DELETE command 317 
in LISTCAT command 371 
user's program, invoking Access Method Services from a 38 
user's I/O routines 527 

using generic (qualified) names for cataloged objects 47 
using one object as a model for another object 75 
using passwords to authorize access to data 53 
using the catalog recovery area 123 
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PAGESPACE parameter 

in DEFINE command 

used to define a page space 83,269 
examples 279 

in DELETE command 3 1 6 

in LISTCAT command 370 
parameter abbreviations 31 
parameter organization (DEFINE command) 74 
parameter set 31 
parameters 

entry-types each ALTER parameter applies to 153 

keyword 3 1 

lists 32 

parentheses within 32 

positional 31 

separators and 32 

summary of 

for the definition of an alternate index 189 

for the definition of a catalog 298 

for the definition of a cluster 222 

for the definition of a user catalog 298 

that apply only to key-sequenced clusters 224 
parentheses, in notational conventions 6 
PARM command 418 
password 

control 53 

(sec also CONTROLPW parameter) 

for nonVSAM data set 56 

given by operator 56 

levels of authorization 53 

master 53 

isee abo MASTERPW parameter) 

read 53 

{see also READPW parameter) 

update 53 

(see also UPDATEPW parameter) 
path 

defining 90,281 

deleting 105 

listing its catalog entry 103 
PATH parameter 

in DEFINE command 90,281 

in DELETE command 317 

in LISTCAT command 370 
PATHENTRY parameter (DEHNE) 282 
performance, optimizing VSANfs 

catalog unload/reload 144 

staging/destaging with mass storage 51 
performance options information, specifying 

for an alternate index 89 

for a cluster 87 
PERMANENT parameter (EXPORT) 334 
plus sign 32 

PN, print chain option 419 
portable data sets 59, 1 1 1 
position, key 31 

(see also KEYS parameter) 
positional parameters 31 
Preformatting control areas 58 
preventing duplicate names in a catalog 72 
preventive measures for protecting catalogs 66 
primary allocation (see CYLINDERS parameter, 

RECORDS parameter, and TRACKS parameter) 
print chain options 419 



PRINT command 144,381 

examples 386 

format 381 

parameter 381 

optional parameters 382 
required parameters 381 

sample output from 382 
print graphics 419 
printing 

catalog entries 103 

catalog recovery area contents 125 

data sets 144 

names of tape data sets open at checkpoint 147 
printing and copying, an example of 434 
processing program, invoking Access Method Services 

from 37 
prompting codes for operator entering passwords 56 

(see also CODE parameter and ATTEMPTS parameter) 
protecting- 

(see also data integrity and data security) 

alternate indexes 89 

catalogs 60 

clusters 58,87 

data 58 

data components 58 

index components 58 

paths 281 

user catalogs 58 
protection and integrity parameters, specifying 

for an alternate index 89 

for a cluster 87 
protection parameters 87 

in ALTER command 152 

in DEFINE command 

used to define an alternate index 190 

• used to define a catalog 298 
used to define a cluster 223 
used to define a page space 270 
used to define a path 281 

nullifying 160 
publications 

related 5 

required 4 
PURGE parameter 

in DELETE command 320 

in EXPORT command 333 

in IMPORT command 355 



qualified (generic) names 49 

in ALTER command 100 

in DEFINE command 72 
example 256 

in DELETE command 109 

in LISTCAT command 103 
QN, print chain option 419 

R 

read integrity 56 
read password 53 

(see also READPW parameter) 
read-only access (see READPW parameter) 
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secondary allocation (see CYLINDERS parameter, 

RECORDS parameter, and TRACKS parameter) 

amount for the catalog 82 
secondary extents, accessibility to 59 
security 

authorization routine 57 

bits in Format- 1 DSCB 42 

passwords 53 
separators 32 

sequence of execution, controlling 31,415 
sequential data set, converting 135 
SEQUENTIALDUMP parameter (LISTCRA) 378 
SET command 418 

examples 421 

format 418 
set condition codes 418 
setting up the master catalog 45 
SHAREOPTIONS parameter 

in ALTER command 163 

in DEFINE command 

used to define an alternate index 206 
used to define a cluster 239 
sharing data 

options modified in ALTER command 163 

specified in DEFINE command 206,239 
SKIP parameter 

in PRINT command 383 

in REPRO command 393 
slashes 31,36 
SN, print-chain option 419 
sort parameters (BLDINDEX) 1 7 1 
sort workfiles for building an alternate index 95 

DD statements that describe the 97 

estimating space requirements for 95 
space allocation for the catalog recovery area (CRA) 83 
space assignment 

to a catalog 77 

to a catalog recovery area (CRA) 83 

to VSAM objects 83 
space estimates 

for a catalog 77 
example of 308 
worksheet for 81 

for the BLDINDEX sort workfiles 95 

for the RESETCAT work file 132 
SPACE parameter 

in DEFINE command 83,291 

in DELETE command 317 

in LISTC AT command 371 
example of output 477 
space, data 

allocating 83,291 

defining 83,291 

deleting 105,317 

extending 82 

for a catalog recovery area (CRA) 83 

space allocation in a catalog's data space '83 

VSAM objects in a 84 
SPANNED parameter (DEFINE) 240 
spanned records 240 
specifying alternate index information 88 

descriptive information 89 

performance options information 89 

protection and integrity information 89 



specifying cluster information 86 

descriptive information 86 

performance options information 87 

protection and integrity information 87 
SPEED parameter (DEFINE) 

used to define an alternate index 208 

used to define a cluster 241 
spreading data sets over volumes {see KEYRANGES 

parameter) 
STAGE parameter 5 1 

in ALTER command 1 64 

in DEFINE command 

used to define an alternate index 208 
used to define a cluster 241 
staging attributes 51 

(see also BIND, CYLINDERFAULT, DESTAGEWAIT, 
NODESTAGEWAIT, and STAGE parameters) 
staging drive 51 
staging from mass storage 5 1 
starting location 

in PRINT command 383 

in REPRO command 393 
STEPCAT catalog 

DD statement for 47 

order of catalog use 
ALTER 100 
BLDINDEX 97 
DEHNE 73 
DELETE 108 
LISTCAT 103 
stop testing 419 
stopping location 

in PRINT command 384 

in REPRO command 394 
storage requirements 

VSAM catalog 77 
STRING subparameter (ALTER) 160 
structure of commands 32 
SUBALLOCATION parameter (DEHNE) 

used to define an alternate index 209 

used to define a cluster 242 
summary of Access Method Services operations 25 
summary of amendments 21 
SWAP parameter 

in DEHNE PAGESPACE command 276 

in DEFINE PAGESP ACE example 280 
syntax 3 1 

system failure, restoring catalog entries after 123 
system's catalogs, example of defining the 423 
SYS 1. NUCLEUS, pointer to master catalog in 45 



TABLE parameter (P ARM) 419 
tape data sets 

for backup copies 142 

for transporting data 58 

open at checkpoint 147 
tape volumes mounted at checkpoint 147 
temporary exportation 112 
TEMPORARY parameter (EXPORT) 334 
terminate processing 416 
terminator, command 34 
TEST parameter (PARM) 419 
THEN clause, in IF-THEN-ELSE command sequence 416 
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user-security-authorization record (USAR) 
in ALTER command 155 
in DEFINE command 

ALTERNATEINDEX 195 

catalog 300 

CLUSTER 228 

PAGESPACE 272 

PATH 283 

USERCATALOG 300 
user-security-verification routine (USVR) 57 
in ALTER command 155 
in DEFINE command 

ALTERNATEINDEX 195 

catalog 300 

CLUSTER 228 

PAGESPACE 272 

PATH 283 

USERCATALOG 300 
USVR {s^e user - security-verification routine) 
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WORKCAT parameter (RESETCAT) 406 
WORKFILE parameter (RESETCAT) 407 
Work file space requirements (RESETCAT) 1 32 
WORKFILES parameter (BLDINDEX) 171 
write access (see UPDATEPW parameter) 
write integrity 57 
write operation, verification {see WRITECHECK 

parameter) 
WRITECHECK parameter 
in ALTER command 166 
in DEFINE command 

ALTERNATEINDEX 211 
CLUSTER 243 
USERCATALOG 306 

123 
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VERIFY command 413 

example 414 

format 413 

parameters 413 
volser (see REMOVEVOLUMES, VOLUME, and 

VOLUMES parameters) 
volume 

allocating the 84 

data spaces on a 83 

dumping a 61 

identifying the catalog's 80 
volume cleanup 63,101 
K volume mounting required during DELETE 105 

1 volume ownership, VSAM 42 

/" removing it 63 

VOLUME parameter 

in DEFINE command 

used to define a catalog 300 

in LISTCAT command 371 
example of output 475 
volume, mass storage 51 
volume serial number, changing the 64 
VOLUMES parameter (DEFINE) 

used to define an alternate index 194 

used to define a catalog 300 

used to define a cluster 226 

used to define a data space 293 

used to define a nonVSAM data set 266 

used to define a page space 271 
VOLUMES subparameter 

in IMPORT command 354 

in IMPORTRA command 363 
volumes, tape, mounted at checkpoint 147 
VSAM catalog (see catalog, master catalog, and user catalog) 
VSAM catalog cleanup 65,3 19 
VSAM data sets, example of defining 248 
VSAM to SAM conversion 135 
V SAM volume cleanup 63 , 1 1 
VSAM volume ownership 42 

removing it 65 
VTOC (volume table of contents) 42,65 
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